Please note these are purely my opinions.

Use simple tools for simple tasks and always simplify tasks. Rinse and repeat.

First, read this if you don’t know what a markup language is, and then read this

Did you read it? Excellent. So over the past couple of days I have been doing some research to decide upon a lightweight markup language for my documentation purposes.

From my research it seems:

For Simple Notes

e.g. for your text-pad, note-pad, for keeping track of ideas …etc

Use Text linked_files: for cases where you are interested in simplicity of form and content and you don’t care too much about visual appearance and presentation.

As a simple rule, always start with raw text-linked_files by default. If you feel you need more,  you can always copy and paste to other formats later on.

For Short Readmes or Prose to Publish on the Web

e.g. Readmes for projects on GitHub, BitBucket, or quick blog posts …etc.

Use Markdown: this is basically the lightest markup language that exists, however it provides quite a bit of flexibility for formatting short documents (Headings, lists, bold, italics … etc).

But remember do not use Markdown for longer documents, it is really not suited for this (it gets hard to maintain really quickly). Also Markdown was primarily designed for web content (HTML) so if you are preparing documents for print (e.g. pdf) there are better formats especially suited for this, please see below.

Markdown is serviceable for simple short prose, but the instant you need more than basic formatting, you’re on your own.

For Documents to Send to Non-Technical (Office) Users

Use a WYSIWYG document (e.g. libre office) in open format so they can edit it.

*Not a lightweight markup language per-se, but in the interest of preserving friendships and peace  with people used to working with MS Office that swear by it (Why? … oh let’s not go there).

For Long Documentation Requiring Collaboration and Displayed on the Web.

Use AsciiDoc or reStructuredText: These are more flexible light markup languages especially suited for this purpose. Out in the field they are used for writing user manuals,  getting started guides, technical documentation, ebooks ..etc. (Here is an interesting article on AsciiDoc)

Markdown is great to write small and simple documents. But ReST/ASCIIdoc are much better when you want more complex, richer docs.

For Individual Professional Documents for Print.

Use LaTeX: for both flexibility and excellent quality documents (especially if they include mathematics) for publication in print (i.e. for PDF documents that are meant to be displayed/printed as pages).

e.g. for research papers, academic dissertation, Journal papers, curriculum vitae, resume …etc.

LaTeX generates publication quality documents and formulas that look great on paper.

I have personally used LaTeX quite a bit and I really like it, however for collaboration LaTeX is not the best candidate (though there are some alternatives if you really want to go this route): there is a steep learning curve for beginners and you have to download about 1GB just to be able to start working with it locally.

Hope this helps,

Did I miss anything? leave your comments below,



Leave your comments below (or comment directly here).

Thank you for your feedback.