Language for plain text documentation

Question

Hi,

I think about storing project documentation in plain text format. The primary reasons/requirements are:

1. easy for source controls systems to manage and track versions;
2. simple to edit (any text editor);
3. REDUNDANT - no additional software required for preparing the document (not generating the formatted result);
4. can be formatted to HTML or other if using proper syntax.

So the question would be: what would be the best markup language to use for the given purpose?

Some of options are:

• Wiki Format (Very verbose IMO)
• Markdown
• Textile

Thanks.

Answer 1

The format would depend largely on users. What are they most comfortable using? Are you going to provide a wysiwyg interface for unfamiliar users? Formatted output for reading (i.e., as part of continuous integration)?

Answer 2

We use ReStructured Text and the Sphinx toolset.

I'm not sure what "no additional software required" means. This requires Python, Docutils and Sphinx. It generates HTML and LaTeX (which can produce PDF) without much work at all.

Answer 3

I've used quite a few... Markdown, Asciidoc, reStructuredText, Textile. There's not a very big difference between those, except Asciidoc is tied to DocBook. My preferences between them are:

• Use Markdown unless there's a reason not to. Of the text markup formats, Markdown is more or less the winner, at least in terms of popularity. It produces very clean HTML.
• Use reStructuredText if your project is written in Python (it's a community standard).
• Use Asciidoc if you need more sophisticated markup, or if your documentation is large (you can write books in Asciidoc, if necessary). Git uses Asciidoc more or less without any additional styles and it looks very nice.

For my projects, I've switched to using plain text :-). It means I spend more time writing docs and less time looking up syntax for writing docs and checking the HTML output.

Answer 4

I'd personally use Markdown with some tweaks. It is very close to the format I personally use for plain-text documentation. The beauty of Markdown is that it not only generates clean HTML but is also very clean to read as plain text.

Now, as for the tweaks (which could probably be implemented by a preprocessing phase), my documentation format generally looks like:

Header 1 is Indicated By Having the Next Line be Dashes
-------------------------------------------------------

Header 2 Ends in a Colon:

Body text is normal text but EMPHASIS IS ALL CAPS instead of star-word-star or
underline-word-underline. Needless to say, there is only one type of EMPHASIS
in my documents.

And I always hard-insert newlines before 80 columns of text.

  // like markdown, code is indented but I prefer two spaces from
  // margin instead of four - less to type, especially in notepad

This is more to make Markdown parse what I habitually write. You may not need this.