Hacker News Reader

While I definitely understand what the author is saying, the reality is that, for the majority of writing developers will be doing, having something that is easy-to-produce and easy-to-consume is paramount. There are tons of more powerful and flexible options than Markdown, but none that let you create a document that is both computer- and human-readable quite as quickly. Documentation that is written is better than documentation that isn't.

View on HN

Which is why I use rST - just as easy to write, but enough more powerful that I'm not left hanging when I realize I need to do something more complex.

> Documentation that is written is better than documentation that isn't.

I have to disagree with this. I've read too many out of date documents. If documentation exists that isn't correct it is worse than no documentation at all. The only useful documentation is documentation that is correct, easy to navigate, easy to search, and easy to update as the world changes (there might be more?).

Good documentation is better than bad, it is debatable if bad documentation is better than no documentation or not (in part because some bad documentation is worse than others).

Reply on news.ycombinator.com