The Operations Documentation Problem
Documentation tends to be a polarising, all or nothing, topic in the Operations teams I have been a part of. Everyone agrees on its fundamental importance but no one seems to like to spend time or effort producing it. Especially if they see no immediate benefit in it for themselves.
“My code is self documenting”
“It’s all in the readme”
“That guy knows – he built it”
This, of course, becomes a real issue when bringing new staff into the team. Onboarding takes far longer when the majority of the information that new hires require about the systems they will be administering has to be acquired piecemeal, anecdotally, using imperfect recollection and without the benefit of an index or search facility.
Storage, input, display and availability are also all contentious subtopics. People have their own favourite wiki flavours, editors and formatting techniques. Should the content be made available outside the team? Or to third parties e.g. vendors? Or even outside the company?
My current role had just such a problem. Documentation was in an awful state – exported in plain text from an old Trac wiki – partially converted to Github markdown in a private repo. A disorganised, incomplete process started by an engineer who had since left the company.
Numerous problems were apparent when comparing the old version of the docs:
- Trac formatting, although similar to Markdown, was incompatible and hence content was mainly unreadable
- Inter-document links were broken and unformatted
- Images were not displaying properly
- Much of the content was outdated, obsolete or plain wrong
How Much Doco Is Too Much?
Legend states that minimum viable documentation for a relatively complex software application should consist of:
- How to install
- How to create and ship a change
- A Project roadmap
- A Changelog
- A Glossary – if necessary
- How to troubleshoot or Where to get help
And for Open Source projects:
- How to contribute
Much of this was lacking for nearly all the projects in our document repository.
So where do you start?
Start by being systematic. Some considerations:
Get some consensus on where the docs should live
Local file server? Github? Dedicated wiki instance?
Public or private?
Private to the team/group/department/company? Public to the world? Or by invitation e.g. username/pass?
Will you need authentication to edit? Or to view?
Do you need group collaboration on documents? Or will a page be locked to one user?
Fortunately the total amount of documentation we had to manage wasn’t too great, maybe a few hundred pages. So we settled on keeping the docs in Github and using a wiki front end for reading and searching.
First stop was MDwiki which is a nice, simple single file wiki front end. It is ideal for small amounts of documentation or single project wiki sites such as when documentation is included in a Github repo. However we had a significant amount of pages in nested directories. And MDwiki has no search facility.
So we went with Gollum
Gollum is the front end used within Github for it’s repo wikis. So when you click on the link in the right menu, Gollum is the engine organising and serving you the pages.
As a standalone package it works really well to display and make searchable any documentation you throw at it.
As it says in the Gollum documentation it supports a number of preformatted file types:
- ASCIIDoc: .asciidoc
- Creole: .creole
- Markdown: .markdown, .mdown, .mkdn, .mkd, .md
- Org Mode: .org
- Pod: .pod
- RDoc: .rdoc
- ReStructuredText: .rest.txt, .rst.txt, .rest, .rst
- Textile: .textile
- MediaWiki: .mediawiki, .wiki
And Gollum also allows you to register your own extensions and parsers:
Gollum::Markup.register(:angry, "Angry") do |content| content.upcase end