Advent of Technical Writing: Internal Dry Run

This is the eleventh post in the Advent of Technical Writing series, wherein I will share something I have learned from my experience as a technical writer. My experience is primarily in software technical writing, but what you read may apply to different fields, too. View all posts in the series.

Around two months ago, a team member announced he was going to test an open source project on a call and record his first experiences. The end goal was to document points of frustration when getting started with the project. Documentation was thus going to be at the heart of the venture: if the documentation was not up to scratch, he would run into friction. Thus, this became as much an exercise of evaluating the quality of documentation as it was about running the software itself.

I joined the call he was recording, staying quiet and only providing assistance when directly called. Because the team member had never used the project directly before, this was what I would call an "internal dry run" of the documentation we had. In the process, I took notes on the points of friction, which I could summarise and act on later.

At the crux of the "internal dry run" is:

1. Inviting a team member to try to accomplish a goal, with reference to documentation.
2. Asking them to take notes or, ideally, to record their experience.
3. Summarise feedback, then act on it.

I like this methodology because you get to see how someone who is not involved in a project uses it. Indeed, it is better if a team member runs into an issue with your documentation than it is a customer.

When you write a new piece of documentation, you may have it edited by another team member (I say "may" because editing resources are limited on smaller teams). This edit only one step in assuring the quality of your documentation, a topic I expect to talk about in a full post. But no matter how much quality assurance you do, there is no substitute to someone using your documentation from scratch to solve a problem.

In an internal dry run, your team member might find:

1. Missing dependency installations (your development environment will be different from that of your colleague).
2. Topics that aren't explained well for someone not familiar with the project.
3. Content that should be more prominent in the site navigation structure.
4. Software bugs (which you would then report to the software maintainers internally, if you are not a direct code contributor).
5. And more.

This internal dry run caused me to restructure the documentation for a project and dedicate time to writing new guides and tutorials. In the end the team member who did the dry run reported that the edited documentation was an improvement over the last. A win indeed!

You may be wondering "when is the best time to do an internal dry run of your documentation?" For a single page, you can do these regularly, although perhaps without the recording component. For a dry run of an entire project, you may do them less regularly, perhaps before a project is live and any time you make significant changes based on feedback.

Of course, the dry run is no subtitute for feedback from users, customers, or whoever the audience is for your content (this could be an internal team, for example, if you are documenting an internal tool). But, it is an effective way to find issues. I plan to do one for an upcoming improvement to some documentation!