Documentation Platform
Plain Text
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.
HTML/CCS
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.
TeX/LaTeX
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 gripe 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 :( Because of the table deal, I stopped using LaTeX and have forgotten all about it by now.
FrameMaker
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...
OpenOffice
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.
MS Office/Word
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!
Word Perfect
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
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.
More details: wiki.html
MarkDown
.md really focus on content rather than pretty facing mark ups.
Minimal markings, just enough so that it can be compiled into html
More details: wiki.html#markdown
I dislike markdown use of # and ## to indicate header lines, mostly cuz
as a techie docs often have lines with # indicating comments,
but MarkDown render these lines with heading emphasis, which is the
exact opposite of the desired effect of using "comments".
ReStructured Text (RST)
.rst is another document generation format similar to markdown.
.rst uses slightly different syntax than .md.
Notably, .rst uses a dedicated line of ------ or =========
under title text to mean header, which is more natural highlight even when reading file as ascii.
Given my gripe on markdown, I will make a switch to .rst and think I will like it better.
A bit more details: in the wikipedia page
NeRSC Shifter as example .rst page
My cheatsheet and trials on rst as rendered by github.
For pre-formatted text (literal block), essentially, use
::
blank line line +
indented text
will be treated verbatim without parsing/modification
but indentation is required
have not been able to find way to do it without indenting the preformatted text
back to normal text
.. code:: bash
# wikipedia says this will be treated as pre-formatted literal block
# with the added benefits of code highlight
# but my experience seems to be that this become an execution directive
# does below just show command or execution of 'date' 'hostname' and 'uptime' ?
date
hostname
uptime
Documentum
TBD.
cmswatch.com
hoti1
bofh1
