Building a Playbook for your Engineering Team’s Documentation
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:
