Markdown is a text editing language, like HTML. If you use Word or HTML to write specs and documentation, Markdown may be a better, more lightweight option for you. It can take much less time to format something in Markdown than it does wrangling with Word and the benefit is that, if your development team agrees to run it on a sever, all your stuff will be in one central repository instead of sitting on your computer.
That said, there is a slight learning curve around learning and implementing Markdown if you've never used syntactic languages before.
Here are the recommendations I've come across:
- Markdown does not auto-generate tables of contents. You have to do it yourself. The "easiest" way if you know command line and you have a Unix-like system is to install Github Markdown TOC.
- If you need to make tables, like say of your SQL structure, you can do it using this handly little site so you don't need to do it by hand.
- Using Mou as an editor on the Mac has been amazing.
- You can generate a tree of your Hg repos (and I'm sure git repos, too) using this tool. In order to put it into Markdown, put tripple quotes around it
|-- yum
| |-- pluginconf.d
| | |-- product-id.conf
| | |-- protectbase.conf
| | |-- rhnplugin.conf
| | `-- subscription-manager.conf