3 ms·

Why you should use markdown: - it will stop your teammates from using e.g Google docs, word files - it can be source controlled and diffed - there are heaps

by abraae 8y ago

Why you should use markdown: - it will stop your teammates from using e.g Google docs, word files - it can be source controlled and diffed - there are heaps of converters e.g markdown->HTML - it's so easy to remember you hardly ever need to go to reference - because it's so primitive it helps focus the mind on keeping your doc simple too - there is so much markdown doc around that there is no cognitive dissonance/distraction for people reading your doc- the format is familiar to them already - after a while I've come to appreciate things that are primitive but widely used - it's convenient to say"just use markdown" and cut the bike shedding off at the pass

eesmith 8y ago
The author wrote "If you are considering Markdown, I hope that you also look at Asciidoctor and Sphinx. I find them to be much better toolsets for writing documentation." These meet all of your points except that people can't transfer their previous Markdown experience for them. FWIW, my documentation is in Sphinx.
throwawaymath 8y ago
A few of these are good arguments, but a few are not. You're right that Markdown is very easy to remember and you don't need to refer to documentation much (if at all). It's also very simple and encourages document simplicity. I like Markdown for personal note keeping. And reading Markdown is not much different from reading But you shouldn't use Markdown just because it will stop your colleagues from using other suboptimal document stores. If you're writing documentation you should do it the right way, which is not by offering a poor tool to curb the use of an even worse tool. That's not a professional and scalable way to find a robust documentation solution. That argument would hold up better for a use case like internal documents, in my opinion. Likewise other documentation formats suggested in the article can be source controlled and diffed - there's no reason why you can't use reStructuredText in this way, for example. And there are also heaps of converters for these suggestions, but unlike Markdown their conversions to HTML will be common and well-specified :)

by abraae 8y ago

eesmith 8y ago

The author wrote "If you are considering Markdown, I hope that you also look at Asciidoctor and Sphinx. I find them to be much better toolsets for writing documentation." These meet all of your points except that people can't transfer their previous Markdown experience for them. FWIW, my documentation is in Sphinx.

throwawaymath 8y ago

A few of these are good arguments, but a few are not. You're right that Markdown is very easy to remember and you don't need to refer to documentation much (if at all). It's also very simple and encourages document simplicity. I like Markdown for personal note keeping. And reading Markdown is not much different from reading But you shouldn't use Markdown just because it will stop your colleagues from using other suboptimal document stores. If you're writing documentation you should do it the right way, which is not by offering a poor tool to curb the use of an even worse tool. That's not a professional and scalable way to find a robust documentation solution. That argument would hold up better for a use case like internal documents, in my opinion. Likewise other documentation formats suggested in the article can be source controlled and diffed - there's no reason why you can't use reStructuredText in this way, for example. And there are also heaps of converters for these suggestions, but unlike Markdown their conversions to HTML will be common and well-specified :)