Building a Playbook for your Engineering Team’s Documentation

Jonathan Fielding
5 min readMay 5, 2023
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:

--

--

Jonathan Fielding
Jonathan Fielding

Written by Jonathan Fielding

Staff Engineer working for @Spendesk, speaker about web things, writing about tech, contributor to open source. If you like what I write make sure to follow.

No responses yet