Git for Non-Developers

I have been thinking about this for quite a while, particularly as I am in the middle of contributing to a project at work to combine our multiple knowledgebases into a single repository of runbooks.

We’ve chosen to resolve our fractured information repositories into a central git repository. Each runbook is written in Markdown.

So why use Git (on GitHub) and Markdown?

1. Runbooks live close to the code, eventually commonly used runbooks can become Ansible playbooks.
2. Markdown is fairly easy to learn, you don’t need to know how to code to contribute.
3. Markdown is still ledgible when not rendered.
4. Every contributor and consumer has a full copy of the repository offline so should be able to read their content in a datacenter where there is no internet connectivity available.
5. Contributors have to follow a workflow that means the content is peer reviewed before being able to merge into the master branch.
6. Every document is versioned and changes audited with git log and git blame.
7. Multiple people can contribute to a single runbook prior to publication and the merging of their work is handled well.

What challenges have been faced?

Needless to say there is a period of adjustment required. With our knowledge and experiences “documented” loosly in Google Sites pages, wikis, support tickets, notes on people’s desks and in our heads - every person has their own workflow for “documentation”.

What we need to consider is that the content of this documentation is very technical in nature and written by some very skilled individuals, but written by individuals who don’t write a lot of code day-to-day and may not have used git before. What problems does this cause?

1. Git has a steep learning curve when starting off, understanding the workflow takes a significant commitment of time. This time commitment is not easy to fulfil when working in Operations or Consultancy.
2. Git has its roots in development, after all Linus Torvalds wrote it to fulfil an SCM role in Linux Kernel Development. The workflows have to be explained and adapted slightly differently for writting documentation.
3. Tooling is tricky, GUIs can be a bit hit and miss with the level of control over your project. CLI isn’t as easy to set up on Windows as on Linux/MacOS.
4. Rendering of Markdown locally can differ from the rendering on GitHub.
5. There are a lot of steps in the process to publish a document.

What can we do to make things easier?

William Chia, GitLab, presented “Empowering non-developers to use Git” at Git Merge 2018. Chia reduced the problem down into 3 requirements:

1. Something to version
2. Somewhere to publish
3. Some way to stop explosions

We’ve already established points 1. and 2. - We are versioning runbooks and then we are publishing to GitHub. What we have started looking at but not perfected is point 3.

Point 3. is currenlty being managed by manual steps, which is fine, but it takes a lot of engineer time and commitment. Mistakes can also be made and a non-consistent, “ad-hoc” process is used.

How can we start delving into stopping explosions? We can reduce the engineer hours involved in publishing content by linting, spellchecking*, ensuring the correct template was used, etc.

This becomes part of our Continuous Integration (CI) strategy, and starts to drive the behaviours for writing more consistent runbook entries (in sourcecode and content).

_* spellchecking is not always easy in technical documents_.

Where do we go once we have implemented continuous integration?

As mentioned above with point 3. we are starting to look at continuous integration to stop our explosions.

We can actually re-iterate on the problem by looking back at point 2. and how we publish. We are relying on GitHub as a platform to publish on, making use of the markdown to HTML conversion that goes on in the background against a GitHub repository.

This is great, but not everyone in the organisation will use GitHub to consume content. How might we tackle this?

GitHub actually supports hosting websites (like this one), written in markdown but presented in converted HTML. This is done using a Static Site Generator (SSG), such as Jekyll, Hugo or Pelican.

There are even SSGs that are designed for formatting technical documentation. Take a look at Sphinx or MkDocs.

So there are tools to build our markdown as a site, whilst we are already checking the sourcecode with our CI solution, we can then start deploying it automatically. So begins our possible new Continuous Delivery (CD) strategy.

Video on YouTube

Below is the full video of William Chia’s talk, which quite accurately describes the issues face when non-technical (or even non-development) users are asked to work in git. The video gives a taste of the solutions used at GitLab.