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.