Documentation Hell
By Jacob Cohen | July 23, 2003
Lately I have been writing a lot of technical documentation, and have begun to realize that Microsoft Word is not a great tool for my needs. When I’m writing documentation, I don’t need WYSIWYG capabilities, just a simple formatting language that does what it should. I suppose I don’t use Word often enough to know the ins and outs of how to use all of its features, but it seems that a good portion of my time is spent dealing with trying to get the document into the right format, or to get an inserted Visio diagram to inline itself with the text instead of floating above it, and so on.
For this reason, I have begun writing all of my drafts using a Wiki. If you don’t know what a Wiki is, here is an example. The particular Wiki I use is MoinMoin, a very full-featured Wiki written in Python by Jürgen Hermann. The advantage of using Wiki is that it provides a simple formatting language that is easy to inline with the text you’re writing without hampering the readability of the text source. I see this as an advantage over WYSIWYG editors in certain respects, such as the fact that you don’t have any “invisible” formatting going on. Everything is in plain sight. The problem with WYSIWYG is that, while you get what you see, it is often difficult to determine how, precisely, to achieve a desired change in what you see.
