Doc Writing Strategies for Engineers: Part Five: Plan Your Doc Strategy

National Capitol Columns — Washington, D.C, via Wikimedia Commons

You’ve learned three strategies for improving your docs when you don’t have a tech writer to help you (InDoctrination, the DocAthon, and the DocCycle. Now, let’s take a look at them all together to help you come up with a plan for using them.

While each of these strategies has an optimal focus, there’s nothing stopping you from making use of them all. Let’s look at a few ways different teams use the strategies alone or in combination.

Doc Strategies in Action

Take the Titan Service team, for example. The Titan team owns a new product which is going into version two. They want to keep their V2 docs in pace with their development. Here is their plan.

• The team has a monthly 2-hour mini-DocAthon that focuses on the existing backlog of doc user stories. New team members attend at least one of these before their InDoctrination onboarding.
• Each new team member completes a 3-day InDoctrination as part of onboarding.
• The team runs the DocCycle every sprint, making sure that there is always a generous doc backlog to work on.

In another example, the Nibelung Product team has an established product which has little churn. Most of the doc changes are due to operations bug fixes. It’s a popular team assignment for getting new employees familiar with the product. Here’s what they do:

• The team assigns new people to a 2-day InDoctrination task. From that point, the new person owns all the docs for a few sprints. The team knows that it’s good to cycle the ownership task among team members, so in a month or so, somebody else gets the assignment to own the docs, and the newest team member becomes the doc mentor.

And, finally, consider the Red Branch team. This team is starting a brand new product from scratch.

• The team runs the DocCycle, treating their documentation as a core feature.
• Once they approach beta, they plan a DocAthon to smooth out any rough edges.

These are examples of what your can team can do to keep your docs in good shape without any help from a tech writer. But sometimes you do need some help. Not so much with the writing part, but just figuring out what to do. For that you need to call in the professional. You need Dr. Doc, who we talk about next.

Learn About a Dr. Doc Checkup

Let’s face it. Sometimes, even though you have everything in place, there are some things you can’t do alone. Resetting that modern hands-free dryer that won’t start. Keeping your dog out of the cat litter box. Explaining to your kids what a typewriter is. Was.

When it comes to documentation, you may easily find yourself in this situation: you want to reorganize your online docs but don’t know where to start. Perhaps you suspect that your latest pages aren’t being found during a search. Or maybe you need to exchange information between unrelated platforms. For things like this, you need to call in Dr. Doc.

We’re talking about your friendly neighborhood content professional. Sure, this is likely a tech writer, but it can also be anybody you know who’s really good at docs: a UX specialist, a graphics designer, a doc manager, or a marketing lead. It doesn’t matter so much what the person’s title is, as long as you respect their knowledge of documentation.

OK, I Found Somebody. Then What?

One thing you need to understand when you start this process is that you engage Dr. Doc for an analysis of your documentation. This person isn’t going to do any documentation. They’re going to spend some time with your docs, peeking in all the scrubby corners, and thinking about your concerns or vision.

When you first meet with Dr. Doc, there are four things you need to do.

1. Give a full overview of the team. That includes the team’s history, the products or services, and a complete overview of the documentation. You are treating Dr. Doc like a complete newbie, so leave nothing out. You want the kind doctor to have full context before beginning.
2. Explain the state of the docs in detail. Ideally you’ve had a DocAthon shortly beforehand, and you can describe content issues, pitfalls, where the doc backlog is concentrated, and so on.
3. State what you want for your docs in the long term. This is your vision. Keep in mind that after going through this doc exam, your vision may change, so make sure you document your vision at the end of this initial conversation.
4. Empower the doc doctor. Give Dr. Doc adequate permissions to review everything. This includes code repos, current builds, admin access for your doc platforms, and anything that you use to manage the content that you present to your users.

Armed with all this, Dr. Doc will step away and spend a few days examining your documentation.

The Follow-Up Visit

After examining everything, Dr. Doc will come back to you with recommendations. What these recommendations are depends on the state of your docs and what you want out of all this. There are a couple things to keep in mind.

• You’re going to have more work. Dr. Doc is providing a feature analysis and a blueprint for improvement. So when you get Dr. Doc’s report and decide to implement it, you’re signing your team up for more (though more effective) work.
• Dr. Doc may provide you with a project plan. Any solution you get is likely something that will take time and labor. Again, this is a core feature of your product you are considering. You should integrate the steps into your workflow (can you say DocCycle?) on a reasonable timeline.

Hooray!

OK, you reviewed the several strategies your team can use to improve your documentation. You’ve also learned that sometimes it’s appropriate to call in a professional for the expert advice that will get you moving in the right direction. Congratulations! It’s time to go forth and plan your doc strategy.