3 ms·
I've done my time with LaTeX for years, arguing for its virtues, and once I discovered that I could write Markdown and convert it to LaTeX with Pandoc, I haven'
by tombert 7y ago
I've done my time with LaTeX for years, arguing for its virtues, and once I discovered that I could write Markdown and convert it to LaTeX with Pandoc, I haven't looked back. I feel like a lot (though admittedly not all) of the Markdown rough-edges go away after that. Granted, I don't use Pandoc for "documentation", just technical writing, so maybe that's irrelevant.
Most of the criticisms listed here aren't wrong exactly, but I feel are a bit short-sighted. If you tell people to stop using a language that's well-supported as a rendering tarket in their favorite code-sharing repo, they're not just going to switch to AsciiDoc or TeX and host a PDF on Dropbox...they're going to stop writing documentation entirely, or just do some crappy attempt of doing "documentation in the comments".
As it stands, I think slightly-NSFW quote says it well: "Documentation is like sex...when it's good it's great, when it's bad it's still better than nothing.".
- afarrell 7y agoI think the last sentence hurts your point. There is definitely painful sex which is worse than nothing and there is definitely misleading documentation which is worse than nothing. Markdown is good because it is much easier for someone to notice it needs to be updated and to fix it without yak-shaving.
- tombert 7y agoFair enough, I just thought it was a humorous aphorism more than anything. Yes, documentation can be out of date but even then it's often still more useful than not having any. I agree with markdown being a lower barrier of entry than most other stuff, increasing its appeal.