Documentation Strategy

Documentation is one of the key pillars of good software engineering, but what good documentation looks like is the purpose of much debate. In this section, we’ll attempt to define what our minimum viable documentation (MVD) level is, why this is needed, and what good looks like beyond MVD.

Minimum Viable Documentation

As the SRE domain is a fairly expansive one, with many patterns in place, learning it is hard and requires a lot of time; both to pick up the context of particular patterns and to become familiar with the plethora of solutions in place over the years at Storio. Although we aim to reduce complexity by synergising around a set of patterns and approaches across our product stacks, it’s still important to document, both for times when there is important context to a particular implementation that should be shared, but also when a more unusual pattern may have been used to create a solution to a particular problem. To that end, we’ve introduced the concept of Minimum Viable Documentation. To us, this is a level of documentation required to be able to adequately explain the project or solution to another engineer in the SRE space. We roll up having MVD present as part of a project into its definition of done.

MVD consists of:

• A Basic problem statement and solution design
• More to follow

Knowledge Transfer Sessions

In order to keep sharing knowledge, the SRE Chapter runs regular SRE Guilds. Guilds can be used for KT sessions, where one member presents on a problem space they have been working on recently. Before attempting a KT on a particular solution or project, MVD must have been reached. The purpose of an overview KT Session is to provide a wide group with an overview of a particular problem solution as a starting point, not to be the only single action of handing a solution over to colleagues. The next step on KT is to do paired deep dives on a particular solution to teammates in your workstream, where the teammate performs the steps needed to deploy, maintain or upgrade the solution. A good example of this, using GitHub Actions Runners as an example could look like:

1) The GHA Runner repositories documentation is brought up to the level of MVD 2) The lead engineer on the GHA Runner project does an overview KT session to the SRE Guild covering the solution 3) The lead engineer does a paired KT deep dive with another engineer in their workstream, performing an upgrade 4) Step 3 is repeated until several engineers have a competency in the solution 5) Documentation is enhanced above MVD based on feedback from the KT Deep Dives.

At the end of this process, a project is considered transferred into the collective capability of the SRE Chapter.