The One Mistake To Avoid When Writing Documentation

Content
09 November 2016

Call me a sadist, but I love documentation. I love writing it and reading it - but I only enjoy the latter if it's well done. Documentation shouldn't be feared, which is why I strive to create documentation which is concise, clear, and accurate. But if you make the mistake of becoming too comfortable with your project it can threaten to turn your documentation from great to suboptimal.

On a recent project, I was creating procedural documents for several processes. To figure out what to capture in the document, I had several interviews where I'd have the client walk me through how they perform these processes. After the interviews, I'd go back to my desk, listen to the recording of the interview, take some more notes, jot down some questions, and start to create the document.

After I was done with the first few documents, I ran into a roadblock. When listening to my interview recordings, the client would say something like "And in this part, it's the same steps as this other process." I told myself, "Ok, let's just go and copy and paste those steps from the other process."

Now that I pasted the steps and updated the pertinent content via a Find and Replace, I wanted to make sure everything was correct. To do this I began to look through supporting documentation and assets. It became apparent very quickly that this new process was in no way identical to the other process.

My mistake wasn't copying and pasting; my mistake was taking the client at their word that it was literally the same steps as the other process.

It became apparent to me that I was too comfortable with the client in these later interviews.

That's when the panic set in.

I started to panic because I was marching to a cadence of doing n many documents a week and felt as if my timeline was in jeopardy because I didn't ask the right questions and I'd have to deviate from my cadence.

Plus, I would need time to figure this mess out. I have no shame in asking follow-up questions, but I do not want to inundate the client with emails or follow-up meetings. They say that animals can smell fear. I didn't want a torrent of emails and meetings to overwhelm the client or have them lose confidence in the deliverable or smell my fear of failing at documentation.

You might be saying to yourself, "Erik, haven't you read Anne Lamott's famous essay? That that's why authors go through multiple drafts of documents? This can be fixed during revisions." Yes, I've read that essay, and yes revisions are great, but I want to knock this out of the park on the first draft.

So how did I quell the panic? A combination of emails, some small desk side conversations, and some independent research. Since the processes were very similar, I was able to do some educated guesses that turned out to be correct. I did this by doing some research on a file share and asking myself questions: if it's this way for Process A, how might the client do this for Process B? For that one thing that's different, how different is it?

My advice for anyone doing user interviews, whether for documentation or something else, is to not get comfortable. I know why this is difficult: as a project goes along, rapport builds, both parties become comfortable and let their guard down. While this is great from a rapport perspective, from an information gathering perspective this is more of an impediment.

Comfort and rapport aren’t mutually exclusive. So don’t be too comfortable. I believe the best way to avoid getting too comfortable is to pretend you're a journalist. Question anything and everything. If someone says it's the same, press them on it: how does this work? You say it is the same, but is it literally the same, or are parts of it similar? Can you show me how this is done?

My mistake wasn't that bad in the grand scheme of things, but it gave me anxiety and forced me to ask questions I should have asked much earlier. By following my advice, hopefully you can refrain from being too comfortable during the interviews, but being very comfortable when you write because you know you have captured all the detailed information needed to write great documentation.

Loading Next Article