Smart Documentation
I’ve made the decision to tightly integrate documentation into SavageGardens. I hesitated to talk about this aspect of SavageGardens because programmers don’t think of documentation as a language. Still, the goal for SavageGardens is to extend our ability to manage massively complex projects. Documentation is important for large projects, therefore I am including it.
It is a somewhat controversial decision to include documentation as part of the source code. It makes SavageGardens a rather complex application in itself. I am actually asking to integrate a wiki data and discussion forum data inside the source code. It changes the face of SavageGardens but, so be it. I see it as the future. A future which I first saw in StarTrek the Next Generation. That TV Show has several scenes where Geordi La Forge documents his work and accesses documentation. That is the goal. That is the dream.
In SavageGardens, Sub-Layer 0 or the ground level is designated for this purpose. Everything on this layer is strictly for human consumption. Human-to-Human communication. None of its constructs will translate to actual code that the machine will see. Never the less documentation will be tightly integrated into the source code, because part of my design goals is to facilitate in code comprehension and code navigation.
How is documentation related to code comprehension is pretty straight forward. Most of use make use of tutorials before we start using a new library or platform. Why not allow the designer of those libraries to include a tutorial as part of his source code. Let the senior developer include a couple of diagrams as to how the data structures or APIs are structured.
Using documentation for code navigation is new and revolutionary. Most of us navigate code by opening a file manager, going thru the directories, opening and closing source files trying to find a lead or a clue that will help us. Some of us are bit more clever and use grep to do the searching. I find that approach archaic. The future I want to live in is one where you open the source code and you find diagrams that visually outline how the source code is organized. Then you click on parts of these diagrams to navigate different aspects of the source code until you find what you want. Hollywood style.
In the diagram above, its a case use for a team manager. Lets say you are a team manager and you want to audit someone's work. You pull up the smart-diagram of your team. You click on the person you want to audit. It runs a script that pulls up everything he worked on recently. Then you click on what you want to audit. That is code navigation like few of us have seen before.
The following are a set of constructs I am considering. I am borrowing some ideas from the web. I am not importing technologies from the web thou. I see it done all around me and I don’t like it. Apps these days are pretty much integrated web-browsers.
1) Hyper text: The idea to click on text and it brings up source code. Or vice versa. Clicking on a function call and it brings up related documentation. Rather then HTML, I will probably adopt a simpler format like markdown.
2) Smart Diagrams: This idea is the same as image maps in HTML. You have a picture or diagram and certain areas are clickable. This is how you would navigate source code.
3) Mind-Maps: This is to allow developers to brain storm and keep track of themselves and they proceed with their project. Also used to navigate code.
4) Document side scripting: serves a purpose similar to PHP, it allows for dynamic documentation. Documentation that updates itself as changes are made.
NOTE: constructs from lower layers will cooperate in creating self updating documentation. For example every time you create a variable or function, an entry is made in an internal database that keeps track of them. Depending on the changes certain documents will be automatically created and updated. Quick examples of this is a table of contents, an index table and a quick reference guide.
