Documentation source in markdown
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.
- Our software help files (.chm) are written in Help & Manual and the source text is stored in some a proprietary file format.
- Our knowledge base articles are written and hosted on SmarterTrack - stored in HTML format.
- Simple DNS Plus plug-in documentation, our news articles, and release-notes are all stored in HTML format in a SQL database.
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 :-)