Technical people can often get frustrated with documentation. They don’t like writing it. They want to make it easier to write and update it. And as they’re technical people, they tend to use technical means to deal with problems.
Most technical people eventually want to use Git to manage their documentation. It seems to make sense: documentation is text, their code is text. Why not use a tool used to manage code, for managing documentation? So they put their docs into Git.
I’ve been there! I wanted to simplify my docs, so I decided to put them in GitHub. But after several weeks/months, I went back to putting any documentation that wasn’t code into Confluence. Here’s why.
Most technical people default to using Markdown for their new docs. Markdown files are how technical people today write READMEs for their projects, so it seems like it should be fine for general documentation, too.
Markdown is a great way to convey small, simple bits of information. It has rudimentary text formatting, and the syntax is slim enough that it can be read easily without a parser.
The problem comes when you need to convey complex information, or lots of information, or use lots of formatting. Just try to maintain a large table in Markdown, or even a table where you want the cells to be multi-line. It’s a huge pain.
Quickly you run out of Markdown syntax features, and your only recourse left is HTML and CSS to format the text in more complex ways. The text becomes more and more obscured behind the syntax, and the principle benefit of Markdown is removed (readability-as-text, and simplistic formatting).
For any serious documentation, Markdown eventually fails to deliver a rich enough set of features for a wide range of use cases. Therefore, any documentation more complex than a README should use a format other than Markdown.
For application source code, there are many full-featured solutions out there that can build you complex, beautiful documentation for your code, using the actual source code itself as the original document. It doesn’t matter which one you use, any of them work if you learn how to use them.
For general document formatting, you have two choices: write a standards-compliant rich text document and convert it to other formats, or pick a tool that has its own rich formatting solution, combined with a WYSIWYG editor. This allows you (and anyone else) to create large, complex documents with ease.
Git is a version-control system for source code. It has no features to assist in the navigation of hypertext documents. Therefore, you have to maintain the documents and their links yourself.
If you need to change the name of a file being linked to, you must change the URL in every document by hand. This is simple enough for a technical user to do with shell scripting skills, but links quickly become stale as soon as no one is checking for broken links.
If you want to automatically generate a Table of Contents in your document, Markdown and Git can’t help you. If you want to automatically generate a navigational tree of other pages, Markdown and Git can’t help you. If you want to embed an IFrame of a different document, Markdown and Git can’t help you. If you want to link to bugs and automatically display their status, Markdown and Git can’t help you. And if you want to search through different repositories for a tag attached to a Markdown file, authored by a particular person, Markdown and Git can’t help you. To create a draft of a file, edit it, flip through different versions of the file, move it to different locations, etc, Markdown and Git can help you, but not in any way that a non-technical user would understand.
For these and many more features, the only viable recourse is a Content Management System, or Wiki, or other piece of software designed specifically with a rich feature set needed to navigate hypertext documents.
With Git, accessing and modifying content requires mandatory access controls.
First, you must have a repository to publish documentation to. Which GitHub organization would you like to use? You’ll need to request access to it. Then, you’ll need to request access to a repository, or create one. Then, you’ll need to request write access to the repository. Every single user must go through these steps to be able to find, read, and write in this document.
With a CMS or Wiki, the default is open access. If you have access to the CMS or Wiki, any user can find any documentation, read it, and modify it. An author must explicitly lock down documents that they don’t want read or written to. This enables more people to easily find and collaborate on information openly within an organization.
Some CMS and Wiki software allows making comments, or “discussions”, on each page. This enables a community of users to discuss what has been published close to the source of the document.
Git does not provide this functionality. GitHub does provide comments on pull requests and issues, but those are not directly attached to the document in question, distancing the discussion from the actual content, and making it difficult to find later.