Wednesday, November 1, 2017

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 :-)
  • Image files follow source text files in the Git repository. In other systems, images are often stored separately from the text.
  • 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.
  • The possibility of publishing the documentation source as public Git repositories, which would allow anyone to contribute in a well established manner. GitHub (and other similar sites) provide very nice interfaces for editing markdown files directly.

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

Share: Facebook /  LinkedIn /  Google+ /  Twitter    
Copyright © 2006-2017 Jesper G. Høy