Lazy-load documentation process that works.

Some background

Can you recall the last time you started at a new company? Remember being overwhelmed with all the new information? Developers, not only have to understand the business, the processes, the vocabulary but also the technical details of all the systems that "make the company go". Do you recall how your onboarding took place? Some seasoned employee spent hours sharing more info with you, that can be handled in a day? A good Scotch would have helped. You took frantic notes that although helpful, never proved adequate? Reviewing such notes generated more questions that perhaps you had the opportunity to ask in another session, this time with Scotch on the table? Nah, I am dreaming; there were no more sessions. Perhaps you were pointed to documentation? That is more rare but it happens. Wasn't that fun?! What is even more rare, is for this documentation to be sufficient or up-to-date or, well, how to say it gently .... was 'interesting enough' that you made it though it without Scotch!

As an IT professional with over 15 years of consulting experience, I go through the process every couple of years. I've seen it all, and I have been been on a quest to solve the problem of communication via documentation for a long, long time. I have developed a system that works. I say this with confidence because I was able to observe its implementations closely and continuously for over a decade. And it works better than you can imagine. I feel like cure-it-all snake-oil salesman saying so, but it is true. It has the capacity to radically transform your organization in a mater of months, and it is very inexpensive and painless to achieve! I hope I do not have to list the benefits of a robust and up-to-date documentation - we'll take that for granted.

Documentation anti-patterns

Just a few things that we will not do and why.

"The Senate" means "an assembly of seniors"

We will not rely on Senators ...

... to onboard new hires via meetings

Originating in Ancient Rome, "the Senate" literally meant an assembly of the seniors(1). Basically, people who have been around, seen many things and could advise on this or that. Every company has their Senate. A group of senior people or SMEs (subject matter experts) who are called to onboard new hires in long, coffee fueled meetings with whiteboards and such. This is not good. It is incredibly inefficient, ineffective, and remember that SMEs leave and die... I want robust documentation that resist both. I want new hire onboarding to take as little time from the senators as possible.

... to generate documentation

Often, a group of lifers - eh, I mean SMEs - is asked to document their processes or systems. They hate and will resist this work. Some because it is boring, and they are right. Others out of fear loosing their importance or job security. If pushed, they will produce crap that no one will ever find useful, mostly. Even if by some devine intervention it is good, it will soon become old and stale.

Note that it is impossible for anyone to write any kind of sufficient documentation, how-to or plan in isolation, without someone from the outside trying it out. I do not mean "reviewing" it. Reviews catch spelling errors. Assumptions will be made and not all steps, not all detail will be included. The only way to ensure the documentation is complete, is to have an outsider to try it, step by step. That is exactly what we'll do...

The process

The process is rather straightforward. Documentation is seen as a pragmatic and 'living' (constantly improving, constantly adjusting and updating) effort. Like an artificial neural network! The following process will achieve this goal.

At start (we assume documentation is missing or inadequate), we generate starting documentation as easily, quickly and pain-free as possible - usually in form of a recorded onboarding meeting. We start the process with a new hire. A SME explains to the new hire how something works, how something is done, and this is recorded. The new hire is asked to summarize what they have learned in form of a written document - a wiki works best. It does not need to be perfect, but since the writer has a video to reference, the result is going to be pretty good. Since we know that things may be missed, the video has to be kept and linked from the wiki as supplemental documentation. Anyone confused by the wiki, can watch the video and update the wiki as needed.

Next new hire is asked to rely SOLELY on the wiki for onboarding. Referencing the video for answers if the wiki is not sufficient. Wiki should be immediately update by the new hire if the video is found to answer what is missing in the wiki. They should note any unanswered questions, note any possible outdated info AND THEN request a meeting with the SME for clarifications / more info. This meeting should also be recorded. It should be added to the wiki's as supplementary video material. Over time, there will be a set of videos attached to a wiki.

The process continues with every new hire. The documentation becomes more and more robust, assumptions are made explicit, all questions are answered. The documentation is constantly improving. A true 'living' document.

That is all. Simple, easy and effective.

Why does it work?

It is easy and pain-free to start. While SMEs may not like to write documentation, few have a problem demonstrating their deep knowledge in a live meeting. Recording the meeting is sometimes a bit of a problem. Again, job security fears or just shyness may come into play. It is something that has to be pushed. I find it really beneficial if the new hire start work remote, since all onboarding meetings are over a call /video anyway. Perhaps cameras do not need to be on for the recording.

This process fixes the issue of assumptions resulting in incomplete documentation. This is especially true for HOWTOs which have a well defined result. Who better to review the process without any assumptions than a new hire? But even the new hire, will hear things and will bring their own assumptions. Hence the process is constantly repeated. Every new hire, relies solely on the documentation to onboard. All wrinkle will be ironed out in 3-5 iterations. Not only will all assumptions be made explicit, undocumented changes to system or processes will be found and documentation will be updated.

New hires are usually enthusiastic and eager to prove themselves. This is a great first task for them. Takes away from the monotony of the onboarding process as well. The only new hires that did not take this process seriously, are ones that had to be let go eventually anyway. It is a good first test of their ability, character, attention to detail and work ethic.

How to start?

I suggest you start this process with developer HOWTOs. How-to setup their development environments (configure, get code, configure application for testing, run , deploy etc) are perfect candidates for this process since the success criterial is well defined - does the app compile, does it run etc. But all documentation, even general information documentation lends it self well to this process.

Start the process the next time you have to onboard a new hire.

How long does it take?

I found that it takes about 3-5 iterations (hence 3-5 new hires) to get very robust documentation for their scope of work. After 2nd hire, you will already be 95% there, but it is the 5% that takes more time to iron out.

Dangers

The biggest problem is that new hire's questions may be answered outside of a recorded video and not hence documented in anyway. Encourage new hires to people to follow this process strictly for the first 2 weeks. Adopting a Q&A system like Stackoverflow teams can help as well, since the questions are captured there, but that's a topic for another time.

BEST OF LUCK!

----

(1) for history buffs like me, you may find it interesting that the Roman system was designed to be conservative, designed to slow down the rate of change, by giving a lot of respect to The Senate. Being an assembly of seniors, basically "old man", they would tend to slow down aspiring young politicians with radical plans to bring in the utopia, by offering advise on proposed policies and courses of action. Such an idea was present in almost every culture in one form or another, like 'tribe elders' in native communities, and in the Constitution, courts and well, the senate in our democracies. I think we've lost some of that, to our detriment no doubt.