This framework provides a set of opinionated document templates that can be used by internal platform teams to build their own sets of documents. These templates are used interally within Neo4j and we hoped that someone else might find them useful too!
The framework introduces some specific types of docs, which each have their own opinions about how such documents should be written and used. For example, the Lego Brick doc type encapsulates features that can be added to new or existing software by following a section of the golden path.
These templates may be useful for any internal platform team that is looking to create a more formal structure for their internal docs, and that wants to provide a preset template to teams that need to contribute and own documentation. It is intended as a starting point or source of inspiration, your needs and the opinions about documentation that you will want to encapsulate will no doubt be different, so you will probably want to create your own versions of these templates.
This framework may be especially useful to teams that want to break down their golden path into modular sections that can be composed to create specific sets of features within software depending on the developers needs.
This framework includes a number of different document types, internally we use examples to how they might relate to cooking to explain the differences (an idea borrowed from the Diátaxis framework below).
- Lego Bricks - Encapsulates a particular feature set that can be added to software or that can be rolled out as a new piece of software. Effectiviely acts as a wrapper around a section of your internal golden path. Contains a list of prerequisites for the brick, descriptions of the different features the brick adds to the software, detailed descriptions of the steps needed to implement the brick, warnings about going "off-road", and follow-up guidance for the reader. The working assumption is that after a reader has read a Lego Brick document and implemented the brick, they will forget its contents. Unlike tutorials, this is focussed on delivering new features and not imparting knowledge. An instruction manual for setting up a microwave for the first time.
- Migrations - Provides a guide for readers that need to make changes to their software, for example due to a change in the usage of a Lego Brick or due to a change in third-party software vendor. Contains details of the motivations for and tracking of the migration, detailed step-by-step instructions, warnings/FAQs, and follow-up info for migrating teams. A guide for replacing a gas hob with an induction hob.
- Tutorials - Aimed at teaching a reader something, such as how to use a particular technology like tracing in their day-to-day, through some practical exercises. Unlike Lego Bricks, tutorials are aimed at imparting long term knowledge to readers, and should not involve the permanaent modification of software. A tutorial on how to use an induction hob in an every day setting, like making an omelette or a pancake.
- ADRs - Provides a format for writing up a technical decision for later reference. Outlines the pros and cons of each option, the final outcome, and some basic metadata. A journal entry on why you decided to get an induction hob instead of a gas hob.
- Playbooks (a.k.a runbooks) - Allows document owners to outline mitigations that can be taken when software operators run intio difficulties and may need to troubleshoot issues. Sets out the the path to escalate further, intial diagnostic steps, different mitigations that are available with the required steps for each, and any post issue steps that need to be carried out. As with lego Bricks, the assumption is that readers do not retain any memory or the contents after an issue has been resolved. A set of instructions for working out why your oven is not working and how to fix it.
There are a number of different ways you can use this framework depending on your needs and how you present your internal docs. If you have an internal developer portal or an applicable templating tool, then you can add scaffolder actions to let developers create instances of the templates when they want to contribute new docs.
The actual templating of the docs is setup to work wirth Go templates, but you can easily replace the templating snippets to work with other templates.
We use a docs-as-code approach at Neo4j, but these templates should still be useful if you use an internal wiki like confluence.
We also use Backstage at Neo4j, and use the scaffolder let developers create new instances of the different document types. When a new document is created, we create a Backstage Component entity to represent that particular document so that it be found in our techdocs homepage, along with a new techdocs site for the document. We set the entity type to "document" and then use a custom internal annotation to denote the document type so that our techdocs homepage will let users search through different types of docs depending on the kind of thing they're doing, e.g. studying vs building.
In the case of playbooks and ADRs, we also provide developers with the option to associate the document with an existing Component, in this case we still create a new entity, but rather than creating a new techdocs site, we add the document to the preexisting component's techdocs. When we create the new entity we then use the backstage.io/techdocs-entity and backstage.io/techdocs-entity-path annotations to point to the new document (more details are available in the Backstage docs)
- Some of our ideas about the Golden Path come from Spotify's excellent blog post on the topic.
- The Diátaxis framework outlines many great ideas about how document owners should structure their documents based on what the reader is attempting to accomplish. It splits docs based on knowledge acquistion vs knowledge application, and based on reader action vs reader cognition.
