Lost trying to find MS Word Documents? Use Plain Text Runbooks

Use plain text, structured runbooks instead of MS Word.

Inspired by Ken Brittain’s blog post.

Financial Services is still using outdated methods of writing critical documentation.

Recently, I’ve become a fan of the runbook - a short, concise set of instructions to perform a given task.

We still write unstructured and freeform documents in MS Word. Checklists inspired by the Aviation industry and runbooks inspired by big tech can help.

How often are you lost trying to find documentation?

MS Word makes finding the documents themselves and the content within difficult when it is needed most. For example, we can’t search file contents without opening them and tracking changes is cumbersome.

Version control is super-important to create auditable documentation.

The plain text runbook

We’ve had a solution to documentation for a long time: Using plain text files, managed in Git, formatted in Markdown, YAML.

Example

Here is an example of a YAML based plain text runbook similar to the format I use. Images can be linked in plain text.

id: 1.1
title: Example Title
summary: The outcome of this procedure here
time: 5m

prerequisites:
  - List any requirements to perform the task

steps:
  - name: Step 1
    description: Example description goes here.
    action: Run this command here

verify:
  - name: Verify the task is complete
    action: Run this command here
    expected_output: "![Expected output description](filepath)"

Ok - but why is it better?

Ever tried to find documentation relating to a specific topic? Well we can search plain text file contents without opening them - I know you’ve sat for a while waiting for the MS Word file to download and open only to realize it isn’t the right file.

Ever tried to organize documentation into groups? We can label structured files with id numbers or categories.

Ever needed to track changes with a robust review process? I know you have. Then Git based tools (diff, Github/Gitlab) offer this by default.

We can programmatically parse into markdown to generate HTML documentation, which itself can be searched - my favourite is MK Docs.

Most of all once you start using these plain text based runbooks going back to a Word document simply feels slow and cumbersome.