How I write documentation

The process I follow to create new documentation, from the time I start working on a new request, to the time I publish the final product, is a mix of what I’ve read in the literature, what I’ve learned from co-workers, and tweaks I have developed over time. In this post, I introduce it at a high level (I’ll call it my documentation process from now on, for short), and I’ll detail the exciting steps in subsequent posts.

My documentation process

If you look at the diagram below, you’ll see that my documentation process is… gasp… waterfall. Didn’t you read somewhere that I work in agile software teams? How I reconcile the two is a topic for another post. This process comprises eight sequential steps, with some expected back and forth between the draft and review steps:

Sit down with the person who requested the documentation and establish the documentation brief.
Schedule interviews with the persons who are most knowledgeable on the subject I am documenting: the Subject Matter Experts (SMEs).
Research the subject.
Interview the SMEs.
Compose my first draft.
Send it to the SMEs for review, and update it until the SMEs are satisfied that it’s accurate and complete.
Send it to the documentation owner for sign-off.
Release the first version.

1. Write the documentation brief

The goal of the documentation brief is to ensure that the documentation I produce meets the needs of the audience who reads it.

During the documentation brief, I sit down with the person who requested the documentation to determine their exact needs. I have a template that guides me in obtaining all the information I need to be off to a good start. I will talk about that in another post!

After a successful documentation brief, I have a good understanding of:

why I should create documentation in the first place,
who will read it,
what the documentation will cover (I’ll call it my subject for short in the remainder of this post),
the constraints I need to take into consideration (time, dependencies on working software, etc.),
what resources are available to me, such as people I can interview, knowledge bases, or existing documentation.

I always write down the documentation brief and refer back to it throughout the project.

Read here for more details on the documentation brief.

2. Schedule interviews with subject matter experts

As soon as I know what my documentation is about, and whom I can interview (the Subject Matters Experts, or SMEs), I schedule meetings.

Even though I work in an informal environment, I always send meeting invitations to give SMEs some context and let them know what I will interview them about. SMEs are busy, and some of them like to get some heads up to refresh their memory and organize their thoughts.

As a rule of thumb, I interview SMEs individually. I keep the meetings short (half an hour); I will schedule follow-up meetings if we can’t cover everything in the first session.

Read here for more details on requesting a subject matter expert interview.

3. Research

Once I understand the documentation requirements, and meeting invitations are sent to SMEs, I consult internal and publicly available sources of information on my subject. I don’t need to know or understand everything — after all, that’s what SMEs are for — but I want to know just enough so that I will:

understand the SMEs when I interview them,
be able to ask insightful questions.

4. Interview subject matter experts

The goal of the SME interview is to extract all I can out of their brains, and write it down. My motto, during SME interviews, is:

I am allowed to ask any question I want, even if it sounds silly, but I am not allowed to get out of this room not understanding what the SME told me, or wishing I had asked a question I didn’t ask.

I always wrap up the interview by thanking them for their time (and their brains), and telling them what the next steps are:

If we didn’t cover the entire subject, I will schedule one or several follow-up meetings.
I will prepare a first draft and ask them to review it.
As I write my first draft, I may have follow-up questions; I confirm with them that I can follow up if needed.

5. Draft

After I have met with all the SMEs, I compose my first draft. I take time to polish the first draft to maximize the chance that reviewers’ feedback will focus on real content issues.

It’s typical for questions to arise as I write the documentation; or that I realize that I need additional information on one or more points. If these questions aren’t blocking me, I add them to a consolidated list of items to ask the SMEs.

If time allows, I obtain the SMEs’ answers to my questions and incorporate them in my first draft.

Once I am happy with my draft, I send it for two rounds of review: SME review and documentation owner review.

6. Send for SME review

The goal of the SME review is to correct any errors or omissions I may have made.

When I ask all the SMEs whom I interviewed to review my draft and send me their comments, I make it very clear what kind of feedback I am looking for, and how I would like to receive it. I also make them as comfortable as possible voicing their critics. Feedback is good!

I update my draft as needed until the SMEs are satisfied. Once it looks accurate to them, I send the revised draft to the documentation owner.

7. Send for documentation owner review

So, who is the documentation owner? I get a little bit political on this one, and choose my documentation owner when I can. The documentation owner is the individual who will gain most from this new document existing and being disseminated. The perfect documentation owner:

is an authority on the subject I am documenting,
has valuable feedback,
will influence other people to read my documentation.

Again, I obtain and incorporate their feedback, until they sign off on the documentation. Now I can apply a final polish, and release the documentation.

8. Release

The goal of the documentation release is to tell the audience that the documentation exists and can be consumed.

How I release the documentation depends on the media and the audience. It can be as low tech as sending an email with a PDF attachment. And it can be as informal as announcing on slack that I have created a new page in Confluence.

What about large documentation projects?

The process I have just described works well for small documentation projects, which I’d define as meeting all or most of the following criteria:

I know the primary audience well, I have already released documentation for them.
I only need to interview one or two SMEs.
The subject is well defined, I don’t need to break it down into topics.
My gut feeling (supported by a proper documentation brief) tells me that I can complete a first draft in two to five working days if I work on it full time.

Larger projects mean that:

The documentation brief takes longer and may require obtaining consensus between several managers.
I may need to analyze the audience, and clearly define who my primary audience is, and who my secondary audiences are.
I will need to break down the subject into topics and deliver an estimate.
More than two SMEs own the knowledge, or it’s a vast or complex topic that will require several follow-up meetings.
I will have to provide status updates on the documentation project to inform the stakeholders of my progress.
I may only be one of several technical writers contributing to the same project.

Where to find more information

These two resources contain sections on document composition processes:

Tebeaux, E. and Dragga, S. (2014). The Essentials of Technical Communication, Third Edition. Retrieved from https://www.amazon.com/Essentials-Technical-Communication-Elizabeth-Paperback/dp/B010IL414G
- The authors describe their composing process in the pages 19 to 28.
Hackos, J. (1994). Managing your Documentation Projects. Retrieved from https://www.amazon.com/Managing-Documentation-Projects-JoAnn-Hackos/dp/0471590991
- This book applies to large documentation projects with an entire team of writers. Part four, the Implementation phase, pp. 323 – 340, illustrates a writing development process.