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”

“JFGI”

“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.

Our Issues

Numerous problems were apparent when comparing the old version of the docs:

How Much Doco Is Too Much?

Legend states that minimum viable documentation for a relatively complex software application should consist of:

And for Open Source projects:

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?

Authentication

Will you need authentication to edit? Or to view?

Collaboration

Do you need group collaboration on documents? Or will a page be locked to one user?

The Winning

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 wiki

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:

And Gollum also allows you to register your own extensions and parsers:

    Gollum::Markup.register(:angry, "Angry") do |content|
      content.upcase
    end

#Documentation #Operations