Plain text documentation is probably the easiest to write in term of allowing the author just
focus on content and not having to worry about look and style. However, for large document,
it would be rather hard to read. Except for the original RFC and IEEE docs, plain text are
probably not recommended other than short ReadMe style docs.
A next level up would be to use HTML, which is what I have done for these notes.
I actually started with a series of plain text file, and have largely embeded the
docs in HTML file inside <PRE> </PRE> tags. A few places where by I want
highlights I would use Heading tags. Finally, a pretty simple CCS stylesheet
allows for some control on the look of the docs and provides uniformity.
I write HTML using vi, so this approach allow me to largely focus on content
and not having to spend a lot of time to format the document to make it look nice.
Of course, heavy duty HTML editor exist to create jazzy web sites, but that
shouldn't be the focus of documentation.
The major downside I find of HTML documentation is that it doesn't print out nicely.
So, if you need the abilities to create book-like manuals, with pagination, table of contents, index, HTML is probably not the best choice.
This is probably considered old school :) And it does have a significant learning curve. You will be "compiling" your doc to generate output... But once learned, TeX is actually pretty good. It use of tags were probably the inspiration for HTML. It really train the writer to focus on contents and hierarchy of the documents, and let the formatting be done separately at compilation time. It can produce professional looking book-like manuals. There are tools to generate .PS, .PDF and .HTML files from TeX/LaTeX.
I actually liked it a lot after learning it. However, I have a big gribe about the method of creating tables, especially those that need to span many lines within a cell. Such table really benefit from WYSIWYG, and it is a royal pain in the rear when using TeX/LaTeX :(
This is what most technical doc writer use. Extremely powerful for creating table of contents, table of figures, indexes, etc. However, last time I used it, many of the features were still far behind that the mainstream Word Processors. If you have a team of people to generate professional manuals, this would be the tool to use. If you have a small project, probably not the best choice...
If the doc is to be printed and be presented in a easy to read format, and the doc is not too big, this is probably the way to go. If you were to generate HTML from this, it may not turn out so great though. As time goes by, this may become better. But WYSIWYG word processor interently trap the writer to spend too much time in formatting instead of hierarchycally categorizing the contents.
This is probably the most widely used word processor. While extremely feature rich, it is actually pretty anoying for producing technical documents. This is because many of the "smart" feature makes MS Word to have a mind of its own. Automatic list numbering don't flow after some "interruption". Framed pictures float to the wrong page when slightly moved. Tries to generate a gazillion styles when user use the WYSIWYG feature to format text, headings, etc. I wouldn't use it again for creating docs of more than a few pages. Also, MS seems to be imposing license that docs created using it cannot be legally manipulated by other third party tool, such as OpenOffice. This would sucks really big time!
This is likely considered to be old now, even though new versions still comes out. Law firms still use it alot. I really like the "Reveal Code" feature whereby the tags for the formatting are easily seen, so that one don't have to deal with the crazy mind of MS Word.
WiKi is a new comer and has generated quite a sensation. This would constitute a true platform-centric documentation approach. It is web-based and requires a server to host it. It allows an online community to edit the contents. eg, OpenNMS, Fedora main sites are hosted by WiKi. With such server centric platform, it means that the contents creates stay at the web site, and there are no easy ways to "distribute" the documents, like putting them on a CDROM or tar file that goes with a specific product. HTML allows docs to be saved anywhere and be read using a browser (while offline). WiKi isn't focused for this kind of access. If you have a community and wants to keep posting constantly updated, WiKi would be a good choice.
WiKi use its own set of tagging mechanism that is similar to idea of HTML, but different in the token it uses. There will be a bit of a learning curve, but not bad at all.
"LYS on the outside, LKS in the inside"
"AUHAUH on the outside, LAPPLAPP in the inside"