Context

Brain dump of why and how to create and maintain a culture of first class documentation. The term "first class documentation", which I'm not sure if I've coined or encountered elsewhere 😅, refers to a culture of relying on documentation as readily as relying on instant messaging (and more than email).

Philosophy

Good documentation is empowering

If the instructions are laid out, then you need not wait for an expert to do something for you or to have the time and patience to explain to you how to do something that they've already explained to someone else.

Good documentation improves accessibility

Written communication (and videos) can be consumed at the time of your choosing, in the timezone of your choosing, at the pace of your choosing, and is more easily translated into the language of your choosing.

Good documentation reduces the dependence on institutional knowledge

If you become cognizant of some cultural norm that is important to succeeding in your content and may not be aparent to someone coming in from outside of your cultural context, share that info.

Building and maintaining documentation culture

Capture great questions + responses

If someone asks a great question, try to capture the it along with the answer in a discover able location. Chances are someone else, be it a future version of yourself or a new person on boarding, will have that question. Case in point: Stack Overflow - that's literally what they do day in and day out. SO captures great questions and great answers, many of which are relevant for years and years.

Capture discoveries, decisions, and actions from meetings

Good for holding yourself and others account by making commitments explicit
Good for reference and potentially conflict resolution by creating a single source of truth for the what and the why
Can feed into the "great questions" doc

I find that having a single document for meeting notes for each project works well in practice. Doing so

Reduces friction to taking notes, since there is already a place for it
Reduces friction to sharing notes, since the permissions can be setup once and let alone

Keeping docs healthy

Include in on boarding materials. Encourage updates and additions

Reference in convos. Instead of copy pasting or reciting an answer in Slack, link to the docs

Redefine success

Valuable and frequently used are not synonymous.

It's easy to think that not used often means not useful. That isn't the case. If something happens infrequently but has a lot of friction or room for error, that can be some of the most useful docs to produce. Those docs can pay for themselves by saving hours of wasted effort if used even once

Doc no longer useful? That's OK

Sometimes you out grow docs and that's OK. They need not be indefinitely useful, just useful during their lifetime. If it becomes obsolete, try to indicate that

On first class documentation