Existing tools

When it comes to producing texts for a documentation, we find two different approaches on the market:

WYSIWYG

One the one side, we have more or less standard word processors or web site production tools following the “What you see is what you get”-paradigm. While writing the help text, it is from the beginning laid out as it will be shown later to the user.

These programs have the big advantage that they are very easy to use for the unexperienced help text producer. It's the same as writing any ordinary text.

This advantage of indifference to multi-purpose text programs is also the biggest disadvantage of this kind of programs: They do not fit perfectly into the shape of help texts. Especially, content creation and markup are not strictly separated from each other so that an author often has to take means of markup for structural layout.

The huge majority of help text production tools can be put into this group, however.

Command-driven tools

On the other side we have the descriptive approach. This comes far nearer to the structural nature of documentation texts. The author does not see the text as he writes it but he puts commands into the text that describe the parts. A title is not printed as “big font, centered” paragraph, but somehow grouped with a command “title”.

Typical members of this group are the TeX/LaTeX typesetting system or HTML source code generators.

Command-driven or parametric systems can be much more expressive than WYSIWYG tools. An author can describe very precise which item belongs where and how everything is connected. Also, the split between content and markup is much more precise than with the first group.

There are disadvantages, however. Especially the TeX-based systems are extremely unintuitive. TeX is a complete programming language, therefore it is almost impossible to render it “fast and roughly” for a first impression. You always have to parse the whole document and this is time-consuming as interpreting the document is a complex task. Therefore, TeX or LaTeX are normally used in a more batch-orientated way: Write the input, process, control the output. Change the input, process again, control again. And so on.

With HTML-based systems, things are a bit different. HTML is much simpler as TeX, therefore real-time parsing is not a big deal on today's machines. But the syntax of HTML is quite lengthy: You have to open areas with tags, close them again, must not forget something or the document is rendered incorrectly. Producing correct HTML by hand is quite complicated and error-prone.

Conclusion

The conclusion from this overview on the existing tools is not really convincing: There are tools and even different approaches, but there are drawbacks. Especially, writing the documentation always burdens the author with some stuff to take care of which is absolutely unrelated to the actual text to write: WYSIWYG systems tend to put unwanted markup into the text, command-driven systems are difficult to use.