Documentation source in markdown

Play this article

Having used Git with software source code for a while now, I realized that Git would be fantastic with documentation source text written in markdown as well. Easy collaboration, version control, diffing, etc.

Until now, our documentation source texts have resided in different systems and formats, none of which have those advantages.

Converting all this to simple markdown files, will give us the advantages of Git, but also:

  • We can write our own simple .NET program to do HTML conversion/rendering (with the help of Markdig) - giving us total control over the output.
  • ... or we can use standard tools - like Read the Docs, GitBook, and Jekyll.
  • Great markdown writing tools exist for many platforms - like “Visual Studio Code” and StackEdit.
  • Being able to use the same tools for both software source code and documentation source.
  • Off-line editing (it is just a bunch of local .md files) - work on the beach or on a plane :-)
  • Easy to search/replace across all articles.
  • Easy to write scripts to do maintenance across all articles - for example check / update links etc.
  • All documentation source texts will be in the same format, in the same place, and accessible with the same tools.
  • No HTML editor control cut/paste "artifacts".
  • Future proof - because markdown is so simple, it will be easy to convert into any new formats of the future.

For all of these reasons, we will now begin converting everything to markdown files :-)