Even with having Wiki as the main documentation repository, not all documentation ends up in a Wiki. Some documentation needs to be managed as part of the source tree – e.g. Readme’s, compilation instructions and similar. This information is usually either plain text or in some form of text processor format, mostly Microsoft Word compatible. Both have their selection of problems. Word documents are large, bloated, harder to version controlled and not readable in shell environment (try to cat or tail Word document ). The plain text format lacks visual structure and without headlines, bold/italic, font sizes etc is harder read.
Some projects I was working on were trying to use HTML as documentation format – but it was too hard to edit using “programmers editors” … and HTML generated by MS-Word is not much better than binary format from readability and version management perspectives.
One format that works amazingly well is a plain text with Wiki markup structure. There is wide selection of various markups, the one I like the best is the Textile markup (which is implemented by many Wiki systems, including Confluence). Textile is very easy to remember, us natural to read and gives the document enough structure without being in the way. Using Textile as “source markup” allows us to copy and paste the document content directly to the Wiki, should it be required. Textile can be also very easily transformed to full fledged HTML using libraries available for all languages of interest (in my case – C#, Java, Python, Ruby – and hopefully will find something for Objective-C as well) to convert it to HTML.
The best feature of using Textile is that some editors – namely TextMate on Mac – support Textile natively and show headings and font attributes properly even without pre-processing step. And with Preview function even generate HTML right away. The similar can be done using plugin in JEdit as well as in Notepad++ with this syntax file.