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 setup
mkdocs, 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.
Before we begin, you’ll need to have the following installed on your machine:
- Python 3.x
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.
mkdocs.yml file in a text editor and make the following changes:
- Home: index.md
This sets the name of your playbook to “Playbook” and creates a navigation menu…