Doc Writing Strategies for Engineers: Part Two of Five: InDoctrination
Do you remember the last time you were the new person on your team? When you had so many questions about where things were, what things were, how to do this, who to ask about that, and why there was no way to figure any of that out on your own?
Of course you do. Changing roles is part of the 21st-century work culture. Regardless of your company size or the state of the economy, you can expect to have new folks join your team a couple times a year. As soon as those newbies arrive, do everyone a favor and InDoctrinate them. No, I don’t mean you need to empty their minds before filling them back up with your version of reality. I mean, in a phrase, throw them at your docs. Assign every new person to go through all your documentation as part of new hire onboarding.
Should We Do That to a New Person?
Yes! In fact, diving into your docs is great for them, and great for your docs. New team members — especially ones who are new to your company — provide you a level of insight you simply won’t get from people who are familiar with your product.
And new team members want to dig into your docs. This isn’t as much a chore to them as it might be to your veteran engineers. New people want to establish themselves, get noticed, learn everything they need, and start contributing. They know a critical part of this is reading up.
There’s New, and Then There’s “New”
This all begs the question of what is a new person, anyway? It can be anybody: new hire, intern, career changer, department transfer, family leave returnee, even someone you’ve poached for a couple-day hackathon. Anyone who is willing, but — here’s the key — doesn’t know too much about your product. You want that fresh-eyes perspective.
Caution, though. Don’t rely strictly on “green” people — folks who are so new to the domain that they aren’t yet familiar with which way is up. You’ll see this especially with career changers and interns. Throw them at the docs too soon, and you are likely to end up with someone who’s only learned how to be frustrated. Season green folks a month or two before InDoctrination.
But New People Don’t Know Anything
Which is the whole point. They are blank slates when it comes to your team’s work. With InDoctrination, you can exploit that.
New folks see doc issues that are invisible to team veterans. You’ve gone over your stuff 100 times, right? In the back of your mind you know that on the set up notes for Project X you wrote “From the Note menu, choose New” when you meant to write “From the New menu, choose Note.” So familiar, you don’t even shrug about it anymore, but your newbie will be throwing hands up in exasperation. Just like your customers.
People unfamiliar with your product will fall headlong into the content holes that you assume everyone already knows how to step over. No project is an island. You make use of all sorts of dependencies in your designs. That core service that absolutely everybody knows about, knows it so well, in fact, that no docs are needed? Pity the newbie trying to figure out what part it plays in your product. Pity your customers even more.
Now that you have a sense of what InDoctrination is, and who does it, let’s look at how you can make InDoctrination a useful experience for everyone.
Implement InDoctrination
You’ve got some eager and willing subjects, and there’s a small mountain of information that’s ready to be cut through. How do you guarantee a successful experience? Before you launch a new team member into the possibly sinking quagmire that is currently your documentation. Here’s a pre-launch checklist.
Review the state of your docs with your newbie. Of course, this implies that you know the state of your docs, so it’s a good idea to go through them before you set them to task. Running a periodic DocAthon is a good technique to be ready for new hires. (I’ll be writing more about DocAthons in an upcoming article.)
Describe the organization. Point out issues you know about, and introduce them to the main repos — whether they be in GitHub, GitLab, Google Docs, Readme.io, or stone tablets. Point out what your group does, and who you think your main customers are. The whole deal.
Share your vision. Because you are well acquainted with your docs, you probably have some idea of how they could be improved, so share your thoughts on this. Share also anything you think your newbie should steer clear of. I’m not saying prohibit any investigation or deep diving — just make sure new people know your priorities.
Confer the power. During InDoctrination you empower your newbies to fix anything. To prepare for issues they don’t want to or cannot fix, provide details on how to create user stories with the appropriate tags, default field values, and so on.
Decide how long the InDoctrination should last. I recommend at least 2 days, but up to a week is OK if you have enough content to support that length of time. Your newbie needs time to get settled, and get well into the groove.
The Start and the Finish
Once you’ve taken care of the checklist and your new team member is ready to go, don’t just throw your them out into the wilderness. Check in every few hours to see how things are going. New people can easily misidentify sources of truth, causing them to make incorrect assumptions, which can end up in your docs. New folks can also wrongly calculate the effects of key components of your design on your docs. For example, if you make heavy use of Docker or Terraform, terms and concepts from those technologies may be needed in your docs. So keep tabs on progress.
After InDoctrination is over, have your new person present findings to the rest of the team. It’s part presentation, part retrospective. Everybody learns the state of the docs (as seen by a fresh set of eyes).
After the smoke clears, you’ve got a great backlog of doc-related stuff that helps you improve your docs even more over time. And you have a confident new person who has established a useful presence early on in a, hopefully, long and fruitful career.
Pluses and Minuses
InDoctrination is a great way to get new people invested in your docs. It’s also the best way to detect any content pitfalls that your users may be subject to. But it does have limitations.
First, if you don’t get new team members very often, you can’t use InDoctrination as your main documentation maintenance strategy. Your docs won’t get looked at enough. (You should have every new person go through it as part of onboarding no matter what, though.)
Also, while you could rotate veteran team members on “InDoctrination refresh” duty once every few months, the key benefit of InDoctrination — fresh eyes — will not be a part of those doc reviews.
It’s for Everyone, But It’s Not the Final Word
When should you use InDoctrination? All the time. Every new team member should go through all your docs as an onboarding task. Your docs will improve and your customers will benefit.
When you need to go beyond the new-user fresh-eyes approach, there are two other ways to advance the quality of your documentation without a dedicated tech writer. I’ll be writing about the DocAthon option in my next article.
