: Is markdown a good choice for large-scale, web-based software developer documentation? "Markdown" has become very popular for people creating developer documentation due to how easy it is to learn

Vote Up Vote Down

In my experience, no matter what you do you will end up with variances and idiosyncrasies throughout your documentation. People have different expectations for what level of formality, what level of formatting, and what organization they like.

As such, I think what's probably more important than what you choose as your method for formatting is how available you make the documentation for that method and how much you encourage editing. I previously worked at a very large company and we had a lot of inconsistencies and incomplete documentation that made it difficult for me to figure out where everything belonged. Over time though I became comfortable with updating those pages when I learned what their purpose was or what the implied context was and ultimately our documentation became something that was really helpful for both our team and others.

So I guess I think markdown is a good choice but, as with any option, you should encourage all editors to clean things up and fix typos, inconsistent or unclear formatting, etc. as they access pages that have those problems. That way, not only do you address the possible pitfalls of whatever markdown option you choose but also the mistakes and biases of the people editing the documentation.

Here is a list of pros and cons to consider:

Pros

Easy to get an intuition for. People with no prior exposure can read markdown fairly easily and can edit it by essentially just to trying to match the formatting used done elsewhere.
Markdown is generally less busy than other kinds of formatting. There is often more indentation and boiler-plate syntax with other options.
The simplistic input, I think, encourages people to keep it simple with their formatting and to use the handful of tools they do have more effectively.
Easier to think and type. Especially once you get the basics down, it's a lot easier to quickly and confidently build a markdown list while having a conversation than building one in something that requires more boiler-plate.
Since this is a widespread problem, there are an increasing number of tools to deal with any inconsistencies.

Cons

You are limited to the kinds of structures that your markdown of choice provides (e.g. you may not be able to make tables or include images)
Difficult to customize. Often you end up having to HTML anyway if you want something beyond the basic styling options (e.g. add colors, padding, etc.).
It can be difficult to find the boundaries of some structures (tables come to mind). Something the additional context and formatting required by something like HTML can be a virtue.
There is a lack of syntactical support which can be detrimental to SEO and automatic features such as cross-references and indices. However, most search engines are able to cope with this reasonably well and a little maintenance can provide what is needed.

These are the key take-aways I have from working with Stack Exchange, Wikipedia/MediaWiki, GitHub, and others.

(0)