4 minutes
The 3 phases of great documentation
I’ve recently come to the realization that I <3 great documentation. Like it makes the hole in my chest where my heart should be tingle when I create or come across very well done documentation. Over the years I’ve worked with many different sized teams and management styles and they’ve all struggled with getting documentation right. For some teams, they had at most a shared OneNote notebook, or they had a wiki but it was horribly out of date, or the information reflected the organization structure and so key information was locked behind siloed doors. Great documentation can make or break a team. If done well, it can ease the challenge of onboarding new hands and it can also democratize specialization, so your team and company does not have to fear the bus factor.
The Three phases of great documentation are Personal, Professional, and Presentable
Phase 1) Personal Documentation
The main point of personal documentation should be to gather as much information, notes, logs, output steps, etc; and slam them into a plain text format of your choice. Do not worry about formatting or anyone else seeing this documentation. It is for your eyes only, and as long as you can follow it, then continue to build that repository of information.
Naturally, when you take time to place and organize your own notes, your brain is going to make a pseudo index of that information. Key details may be missing from what it is you are recording, but you will most always remember where you put that detail, and then when you need it again, can easily retrieve the information.
Some scholarly folks have even invented an entire “Second Brain” called a zettelkasten around this concept of continually taking notes, indexing them with tags and/or interlinks, and this can be more than just notes at work. These Second Brain’s are for everything; recipes, meetings, shopping lists, and just about anything.
Phase 2) Professional Documentation
This phase is contingent on having some previous notes from the personal documentation phase. This is where you are formally recording notes that you want to share with your organization. Many teams use a form of Wiki or Shared documents to go about this.
The documentation needs to be accurate, true, and above all readable to a wide audience - You never know who in the future may need to understand the whys and whats of your instructions.
Things that a professional documentation system requires:
- Searchability - If you can’t easily search for ANY text within the docs, then it will be impossible for someone else to find your article
- Tagging - Not all documentation fits in a purely hierarchy structure, nor should it be forced into one, so tags are a way to cut across hierarchy and create a new grouping of closely related topics.
- Viewable - Everyone in the organization should be able to view your documentation. Likewise, you should make your documentation understandable to a wide audience, and also be careful of revealing secret information.
- Mixed Media - The wiki system should make it easy to include images, videos, diagrams, whatever is needed for those making and reading to understand the concept.
Phase 3) Presentable Documentation
Most teams stop at step 2, with the thought that so long as it’s in the wiki someone can find it. I’m here today, to tell you that most other people, do not read documentation until forced to. Does that mean this is all a waste of time and effort? NO. The previous phases were for your understanding, phase 1 is explaining it to yourself, phase 2 is explaining it to your team, now phase 3 is you distilling everything down into few slides of a presentation and verbally explaining it to your team or larger development organization.
At my current place of employment, every friday a team from the Engineering department presents on a new or innovative topic that they want to share with the rest of the organization. These are great, people listen and ask questions, you can physically see engagement go from close to zero to a ton of side conversations spinning out as people absorb and then start to imagine using the new tool/concept/idea in their own work.
Likewise, anytime our team builds something new, we do a show and tell, running through both the documentation on our wiki and live demoing the new feature so that everyone understand how it works, why it was made, and what problem it solves. These presentations are recorded for future viewers and are by far the most effective way to spread the word and get team members involved and engaged with the new concept.
Plus, if you can accurately explain a technology or idea to someone else, that means you fundamentally have learned this new skill and you can be proud of the information you have and know that people want to learn from you.