There are many formats that you can write documentation in for the Web. For GitHub projects, Markdown is an accessible format that is cross-platform and compatible with many web editors and CMS systems. This article shows how to add a Wiki to your GitHub project, write in markdown, or use Dom Christie’s HTML to Markdown to convert HTML document to the Markdown format.
The Wikipedia definition is the best I have seen as to why using Markdown is the option for cross-platform documentation. “Markdown is a lightweight markup language with plain text formatting syntax. The format is designed so that it can be converted to HTML and many other formats using a tool by the same name.” (Wikipedia) The GitHub wiki allows you to write in Markdown, allowing you to re-use the same formatted text in markdown files you can include with your project.
You should always add documentation to your projects, especially when the tools are built into each project. In each GitHub project, one of the tabs is labeled Wiki which exposes a built-in Wiki editor.
Start Your First WIKI Page
Once in your site, selecting the Wiki tab will display the Create Your First Page button which you click to start the process.
You will then see the page editor. There are two tabs, that switch from Write and Preview modes which allows you to see how your document looks.
There are a couple of options if you do not write in Markdown, which is listed below. Markdown is useful as you can also reuse the code to add a .MD file to your project so that anyone doing a check out can have instructions or documentation with the code.
Convert Your HTML to MarkDown
I used the site pictured below to translate my final blog post back to markdown by pasting it into the left column and copying the results on the GitHub editor’s right.
The results below are the final version of the documentation. The key was that I was able to take HTML, translate it to Markdown and create the start of a Wiki.
As pictured above, this creates user-friendly documentation. Don’t forget to also save the Markdown file in your repository so that the user downloading your GitHub project also has a copy.
After discovering the tab, I have started using this feature to include documentation and project info with my repositories rather than solely relying on my website. However, having your own website also has its advantages.
I hope this helps as the importance of documentation on a positive user experience cannot be overlooked.