About the docs

My digital tools break all the time. For a given tool, I will inevitably start documenting the things that are likely to go wrong and how to fix them, but I often don't start that process until I've already lost a lot of time due to repeated trial-and-error.

This framework is an attempt at cutting out some of that time before it's wasted by starting documentation with a framework that's easy to start, and more important, that's easy to maintain and improve. There's no one-size-fits-all solution to tool documentation, but by breaking it down into clear components, it's easier to add complexity where needed and keep things simple wherever we can.

Levels of detail

🚅 Normal Use

Level	Description
1	Nothing
2	Feature list - A list of the tool's functions and the most basic instructions about how to do them
3	Basic information - A list of functions with high level instructions for each, plus in-depth instructions for the most common functions, and a note about functions for edge cases
4	Complete information - A list of functions with detail on how each one works and all useful variations.
5	Exhaustive information - A list of functions. For each thing it can do, an explanation of how it works, useful variations, *and why it exists.*

🏗️ Setup and Teardown

Level	Description
1	Nothing
2	Brief, single sentence description
3	List of steps
4	List of steps and sub-steps - Each step has a brief explanation and a list of sub-steps where relevant
5	Fully explained list - Each step has all relevant sub-steps. Each step and substep have all relevant explanations

🧓 Lifespan

How long until things break - either temporarily or permanently

Level	Description
1	Nothing
2	Rough estimate
3	Best-before date
4	Best-before date with most likely failure scenarios
5	A best-before date, examples of how it will fail, and what kind of maintenance is required to deal with each.

🔬 Current Status

How it should be working

Level	Name	Description
1	Nothing
2	Summary	Very short summary of what it's doing
3	Inspection	Summary of what it's doing and how to see that it's doing it.
4	Inspection & Surface Metrics	How to see what it's doing, any additional tests that show anything that the basic status view doesn't
5	Detailed Metrics

🛠️ Maintenance

Preventing things from breaking

Level	Description
1	Nothing
2	List of things that'll need maintenance
3	List of items to maintain and priority list of the top 3 things to do and roughly how often to do them
4	List of items to maintain with prioritized list of maintenace tasks, how often to do them, and how to tell if they need doing
5	List of items to maintain, prioritized list of maint. tasks, how often to do them, how to tell if they need doing, what will happen if they're not done.

🚧 Repair

Fixing broken things

Level	Description
1	Nothing
2	What are the top 3 ways it'll break, and basic instructions on how to fix those
3	What are all the ways that i know it'll break, with basic instructions on all, more complete instructions on the common ones
4
5	How to fix everything i know of.

🤔 Troubleshooting

Tools to figure out how fix new ways that the thing broke

Level	Description
1	Nothing
2	A basic list of useful tools
3
4
5	Troubleshooting tools per system, when to use them, why they're helpful

A good example: Github and Kubernetes docs

There's some stuff that some tools on github have standardized which is really helpful:

basic tool setup instructions
some way of validating that the basic setup is working
basic tool teardown instructions (kubernetes does this well)

These steps give some very basic tools for starting to use the tool, stopping use of the tool, and validation that things are working (or not).

This approach also gives some basic troubleshooting tools, because often you can compare a broken version of the tool to a working version to figure out where things are going wrong.

The traps of digital tools

There are a lot of problems with digital tools that don't exist with physical ones:

Lifespan - they are prone to functional breakdown faster because they often have deep dependencies on other tools
Maintenance - they need to be frequently updated to stay functional (security updates, package updates)
Repair - they are prone to being broken by seemingly unrelated changes, and repairing the malfunction can often involve multiple layers of changes to dependencies
Visibility - often their state of fitness (eg needing updates, needing repair, breakdown) is not visible. Sometimes even whether they are working AT ALL is not visible or obvious.

Instruction must be made a part of the tool

This wasn't a problem with physical tools like hammers: everything you need to know about things like its lifespan, how to maintain it and repair it, and whether it is currently functional can be learned in all of 60 seconds, and it conforms to all of the same rules as every other hand tool

Which instructions are important?

For tools which are not self-evident, there are a few basic things that need to be shared:

what is the tool supposed to do
what are its components
how long is it expected to work (before needing updates, before needing repairs, and overall)
how can i tell if its working? how will i know if it stops working?

Documentation of the Documentation

Publishing a new version of this document

This system uses mike and mkdocs-material. To publish a new version:

Modify the markdown files in the docs directory
Generate a new version. E.g. to push version 0.2, use

mike deploy --update-aliases 0.2

Push the repo changes to git.

Debugging

In order to see the changes to the docs, mkdocs serve isn't sufficient, since it will only build and show the docs without versioning. In order to preview the docs with versioning in place, use

mike --debug serve

Known limitations

Currently the version numbers in mike do not correspond directly to versions in github.