MarkDown, Textile, RDoc, choose your foe

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” 🙂

Advertisements

One thought on “MarkDown, Textile, RDoc, choose your foe

  1. This is an interest article. I am surprised why no one has commented. I am going to try sticking with RDoc for the same reason you mention: no mental switch.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s