When people leave the company, a lot of specific and ad hoc knowledge goes away with them. Unless there is already a strong documentation culture, there’s only so much that can be said and done during exit interviews to make up for it.
But this doesn’t have to be left to fate.
Throughout the month of January, my now ex-colleague Adam Janiš and I pair documented all his knowledge about the frontend infrastructure at Kiwi.com. We produced a 24 page document, fixed a few bugs and addressed some tech debt. More importantly, we had fun doing it!
Here’s how we approached it.
How to pair document
This is an attempt at formalising what we’ve done, feel free to s/Newbie/Robin/g and s/Expert/Adam/g.
The Protagonists
You will need two proactive people: an Expert on the subject to document and a Newbie who is not too cursed with knowledge yet. Bonus points if they have not really worked together but always had good chemistry in their interactions.
The Newbie makes it easy on the Expert for this documentation effort to be a no-brainer:
- they organize the pair documenting sessions;
- they manage the agenda of the sessions;
- they do most of the note-taking;
- they digest the notes into documentation drafts in between sessions;
- they stay curious and eager to learn more about the subjects, with questions always at the ready (this is hard to fake, so find an adequate Newbie for the task).
The Expert shows up at the sessions and generously shares their knowledge with the Newbie, answering patiently every question they may have. They review the documentation drafts to ensure the prose does not betray the original intent of the notes. Bonus points if they include the Newbie in solving similar problems described in the nascent documentation as they arise in the support channels of the company’s Slack: learning by doing is a great way to drive home the material and expose remaining ambiguities.
The First Session
The Newbie is in charge and explains how it’s going to work in the first pair-documenting session. That means going through what’s expected of each participant in this documentation effort as well as giving an overview of the actual process.
The objective of the first session is crucial : go as broad as possible and capture as many ideas of what needs documenting to form a backlog of topics to go over in the next sessions.
This can be achieved through asking questions like (more examples in this template):
- what are things that you know about that very few people know?
- what are the things that people always ping you about on Slack?
- what tasks pile up when you’re on vacation?
Once the amount of things to document gets a bit clearer, see how many days are left before they leave and agree on a schedule to leave enough time for this task.
In Between Sessions
The Newbie transforms the raw notes into documentation drafts and gets the Expert to review them.
As more people in the company are aware of this documentation effort, they might have questions of their own; the Newbie adds these points to the agenda for the next session.
The Expert includes the Newbie in all discussions on Slack touching on the subject to maximize the learning opportunities and give the docs a trial by fire.
A Normal Session
In the first 5-10 minutes, the Newbie and the Expert go over unresolved comments in the doc draft, they review the agenda from the previous session and see if anything pops up to be further discussed or explained, and finally, they review the agenda for the current session and decide what to prioritize.
They then go over each point in the agenda: the Expert does most of the talking while the Newbie does most of the note-taking. The Newbie shares their screen for the document to be visible by both pair documentors. The Newbie may interrupt the Expert at any point with questions or with attempts at paraphrasing what the Expert just described. The Expert glances at the notes being taken once in a while to ensure they don’t contain mistakes from the get-go.
When the time is up, the Newbie and the Expert look at how much they covered from the agenda, move what hasn’t been covered to the next session, and agree on a date and time for that next session (if it’s not already regular).
Tools we used
A Calendar : to plan the sessions, to have automatic reminders for them, and to share the video-conference link.
Custom recurrence with expiry date, Hangouts link, Notification not to miss it, Allow guests to modify event for better collaboration
A Google Document : to store the agenda, the notes and the first documentation drafts. Do make use of the outline on the left-hand side to navigate more easily once the document gets to a certain size. Do make use of comments to discuss and improve the notes and the draft. This is also a good place to involve other people from the company asynchronously. Make sure to put this document in a shared team drive for it to have the right permissions set by default.
Use the “Styles” dropdown to get this hierarchy
Here’s a free template Google document to get you started. Feel free to make a copy.
LucidChart : to draw a few diagrams because pictures are great (though you may want to check out Draw.io for a great free alternative).
Why Pair Documenting Works
What usually happens
Unless there is a strong documenting culture, (1) people never prioritize documentation over almost any other task, because it’s just not as fun as coding or as urgent as the next fire you need to put out. That means that when someone is about to leave, (2) there is an impossible amount of things to document that they don’t even know where to start. Because they are short on time, they end up drafting a lil’ something and call it a day. (3) Anyway, we never needed that, why are they asking me to document that stuff, who’s gonna read it anyway?! (Note the use of two “anyway”).
Clear intention through planning
Through planning the pair documenting sessions, we make sure documentation does get prioritized and give it the importance it deserves. If the Expert’s knowledge is that important and they by happenstance siloed it, it becomes urgent to share this knowledge more widely to deal with that critical bus factor. (Whether they leave or not is almost irrelevant in this case.)
Because we know when the Expert’s last working day is, it is easier to retro-plan the right number of sessions to cover the entire backlog established in the first session. This of course might need adjusting throughout the pair documentation effort.
More fun and better quality through collaboration
Planning is not enough if the Expert is still lost about what needs documenting and in which level of details. The nagging “are they even gonna read it?”-type questions could well be the end of the documentation effort already: a well-crafted plan not well-executed.
With an accountability buddy, things turn around entirely.
It becomes really difficult to bail out of the plan because you know the other person is expecting you to show up at the session.
Because the Newbie is enthusiastic about the topic, the Expert is more generous in their contribution.
Because the Newbie asks questions and cares about details, the pair documentors tailor the documentation to the level of knowledge on the receiving end. The Expert knows this documentation will be useful. 😌
Aligned incentives
The Expert also knows that what they know should be documented somewhere, and because they like their colleagues, they don’t want their departure to create a mess. (Right?!)
The Newbie knows this knowledge is valuable, and about to disappear if they don’t take action. Besides, it’s something they’re curious and wanted to learn more about anyway.
The Expert gets to share their knowledge and teach what they know to someone who’s enthusiastic and interested in the topic; the Newbie gets time with the Expert to learn as much as possible from them.
Parting thoughts
I really enjoyed the pair documenting sessions with Adam and I think they should be made a regular practice, just like pair programming. It’s a great way to level up people while producing value beyond the scope of that collaboration.
At the same time, documentation is only valuable if it gets read and updated continuously. I’ve been thinking about how to bring it closer to where people are already consuming content. For example, this could take the form of digests of parts of the documentation in the company’s Slack.
I’m not super familiar with mob programming, but I do wonder if mob documenting could be a thing to try too.
Acknowledgements:
- Adam Janiš (@adam_janis) for trying out this pair-documenting idea before his departure :)
- Emilia Vidal for her review and suggestions,
- Shawn Wang (@swyx) for his review and ideas for the title and Open-Graph image,
- Ron Au (@ronvoluted) for providing the font to go ahead with Shawn’s ideas,
- Excalidraw to produce the visuals.
Top comments (0)