| < The philosophy | Existing tools > |
Writing a program or structuring a process requires certain resources. Especially someone who does the job. There are two possibilities on that person's affirmation to writing documentation:
The creators of the piece to be documented are capable of doing their actual job, but much less affiliated to explaining the results of their work to others. They need some specialists to do this job in a good manner. Those specialists, however have to be integrated into the project. They do not only have to write their output, but also have to communicate with the original authors about what actually to document.
Assuming a restricted amount of time and resources, we have a negative coupling between these two roles: The less time the documentation authors need for producing the output, the more they have to understand their object.
The project fulfillers do document on their own. Either because they actually like documenting, or because they did not find or had no resources for someone else. While the constellation is different, the problems are the same: First thing in the process is, of course, the actual product. Documentation comes second and has to take the left over time. Ironically, without the product, there is nothing to document...
In both cases, it is vital for the documentation process to be lean and easy to do. Documentation is always about structuring information, so an explanatory information set on a program or process is normally rather strictly structured itself.
Also, a documentation author normally is not interested in revolutionary artwork in his results. While the documentation should not be like a sheet of typewriter output, text markup is not done for itself, but for making the structure clearer. Same is true for images, internal crossreferences and other documentation elements.
Often, a documentation author (especially if he is a programmer doing the docs in his spare time) is even not the right person to decide on any design questions. That task should be done by someone else who knows about the results of certain markups. For example, coloured boxes always attract the reader's conscience.
A documentation tool must give the author the possibility to concentrate fully on producing the text. Additionally, it should give him an impression on the result of his work as direct as possible. Let's see how these two target can be reached with the existing tools.
| < The philosophy | Existing tools > |