- Good documentation is empowering
- Good documentation improves accessibility
- Good documentation reduces the dependence on institutional knowledge
- Building and maintaining documentation culture
- Capture great questions + responses
- Capture discoveries, decisions, and actions from meetings
- Keeping docs healthy
- Redefine success
- Valuable and frequently used are not synonymous.
- Doc no longer useful? That's OK
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).
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
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