Building a Playbook for your Engineering Team’s Documentation

Photo by Blaz Photo on Unsplash

Like most engineers, documentation is probably the part of my job that I enjoy the least however it's probably the most important part. Therefore if I am going to spend time writing documentation I want to make it as easy to find and consume by the readers, ensuring its actually useful.

A way in which I have done this recently is to work with the team to build out a playbook where we organise and share our knowledge. It allows you to create and edit easily and link pages together in a cohesive structure. In addition, by storing it in Git, our documentation is versioned and has a similar peer review process to our code by also using Pull Requests.

In this blog post, I will show you how I recently setupmkdocs, a static site generator to create a Playbook at Spendesk after I joined in January. I will alos show you how to then deploy it to GitHub Pages.

Prerequisites

Before we begin, you’ll need to have the following installed on your machine:

• Python 3.x
• pip

Building your Playbook

Step 1: Installing mkdocs

The first step is to install mkdocs. Open a terminal window and enter the following command:

pip install mkdocs

Step 2: Creating a new project

Once you have mkdocs installed, you can create a new project by running the following command:

mkdocs new playbook

This will create a new directory called playbook containing the basic structure for your Playbook.

Step 3: Editing the configuration file

The configuration file for your playbook is located in the mkdocs.yml file in the root directory of your project. This file contains various settings that determine how your playbook will look and function.

Open the mkdocs.yml file in a text editor and make the following changes:

site_name: Playbook
nav:
  - Home: index.md

This sets the name of your playbook to “Playbook” and creates a navigation menu…