Is markdown a good choice for large-scale, web-based software developer documentation?

Question

"Markdown" has become very popular for people creating developer documentation due to how easy it is to learn compared to most alternatives. Unfortunately there are dozens of "flavors" of markdown and no official standard.

We are creating software developer documentation that will be accessed both through a command prompt and a website. The authors may never bother to view how it is rendered in HTML. It is a large-scale project that needs to be maintained over time with a limited budget. We are evaluating either choosing one of these flavors of markdown or something that has an official standard like reStructuredText.

My concern is that formatting errors will creep in from people who have experience with different flavors of markdown and/or our need for richer syntax will grow over time.

Is the ease of markdown worth the potential pitfalls that may arise? Is there another text-based solution that would work better in this situation?

Answer 1

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.