Ownership & docs form

These two points are better explained with the examples.

Example 1: as a developer of a closed-source piece of software with no public APIs, I probably don’t care about writing the docs in the format of reference. This is because I am responsible for the code, I work with the code on a daily basis and hence I try to write my code to be self-documenting. On the other hand, if today I am an on-duty engineer, I would thank my colleagues for writing a short how-to guide that will help me to quickly fix a rare problem that occurs, say, once a month or a quarter. I’ll likely to write or update such a how-to guide myself until we have capacities or increased problem occurrence to automate the how-to guide, so that it’s the code again and docs are no longer needed. I don’t expect that how-to guides are written by a team lead or a technical writer; it’s developers who need them.

Example 2: as a team lead or a product owner, it’s very likely that I want to have some higher-level understanding-oriented form of docs maintained. So that it’s easier for me to onboard a new developer or explain a a complex concept with its context to someone, etc. I don’t expect devs to write these docs for me, it’s my responsibility and ownership. I am interested in maintaining it and I’ll suffer if the docs are unmaintained when I need to answer the same questions over and over again.

Docs instead of automation or a process

It’s nice to come up with a checklist document for a new employee onboarding:

• add the GitHub account to the organisation
• add relevant permissions on GCP
• send a VPN certificate
• …

It’s much better than not having it at all. But it’s even better if you implement the checklist as a automated process with your Infrastructure-as-a-Code approach. It will take more time to implement first, but once done it’s guaranteed to be maintained.

Same with the managerial work processes. It’s nice to outline it with a document first, but once implemented, keep only relevant forms of the docs maintained by the people who are interested to have these docs updated. They still may need help organising the process of the docs maintenance: e.g. every time when someone disturbs a colleague asking how to do something, they are instructed, but also asked to update the docs with the answer they just got. They can also have a task to update the docs during their on-duty rotation.