Recently i used all 3 of them for various project documentation, and somehow all of the are broken…

MarkDown

Pro:

• Looks like natural text
• Simple, mostly elegant syntax

Con:

• Lists can destroy your layout, try this:

   - test
  
  ### Heading

  The heading will be in your list, thats just wtf… (adding <span></span> before the heading helps)

• No tables…
• Some editors truncate the double space used for linebreaks
• No numbered list, except you add 1. 2. etc yourself

Textile

Con:

• Looks weird with h2. h3. but thats kind of ok…
• You need a free line after each heading, which makes the layout look bloated, especially if you got a lot of sub-headings
• Line break = <br /> very elegant…

RDoc

Pro:

• You can use your RDoc skills for documenting ruby

Con:

• No linebreaks, not even <br/> works….
• to highlight code you have to use <tt>CODE</tt> very elegant…

All

• You can use html to hack most of the things that do not work, but that somehow defies the purpose…

So my personal favorite is markdown, elegant, and if you know you have to look out for those lists its somewhat ok…

But if possible i would switch to RDoc, since then i would not have to make a mental switch while documenting code.

Id like to hear your opinion, or at best a “no thats wrong, you can do xxx with yyy” 🙂