Conducting a technical documentation audit: The first thirty days onsite as a technical writer


Recently during an interview, the director level person I was speaking with asked what I do when I come in as a new technical writer that is the first one inside of an organization. Some of my technical writer roles in the past have been working directly on technical teams (and have been the first technical writer more than once) so I do have a process I’ve come up with over the years but had yet to write down. The key for a successful document audit is to couch everything in business terms especially if the technical writer position is to either start a new group or be a part of a technical team

Here is a basic overview of my documentation audit process:

Get access to existing documentation. I like to read all the existing technical documentation before speaking to anybody. At this phase, I like to look at the documentation based on my own experience tempered against any preliminary discussions about the current state of the organization’s technical documentation as discussed during the interview stage and any preliminary discussions that have taken place. I usually keep a running list of observations of what I see in the documents at this stage.

Get access to existing systems (if workable). An optional step is to get access to existing systems to compare the existing documentation against systems for a document freshness test. I realize this isn’t always workable or even necessary, but I’ve gotten a lot of insight doing this when the project involves reverse engineering requirements documents, software requirements specification, or functional specifications.

Discuss organizational priorities for technical documentation. I don’t admit to having all the answers about the direction of the documentation plan, so I always try to get the organization’s priorities for technical documentation early in my documentation audit. Technical documentation needs to align itself with the business early in the process.

Interview internal customers about the documentation. I’m a believer in aligning technical documentation to the business making me a big proponent of talking to the internal customers for the documentation and getting a handle on their likes, dislikes, and requirements. I especially like to talk to staff members who work on different shifts about their views on the existing documentation.

Interview stakeholders and managers about the documentation. After speaking with the internal customers about the documentation, then it is time to speak with the manager and higher level stakeholders of the documentation.

Develop and present a list of findings. Based on my discussions with staff members, I write up my list of findings and present them to management and/or stakeholders either through a written report or a presentation.

Develop an action plan. Based on the discussions during the internal customers and stakeholders and the presentation of the list of findings then it is action plan time. My action plans typically include:

  • Document priorities
  • Proposed document overviews
  • Project schedule/dates for document development

Execute on the action plan. I like to align my action plan with the projects that the documentation supports and set 60 and 90-day goals for new technical documentation efforts especially if technical writing is a new addition to the organization.

What sort of upfront analysis do you do as a technical writer starting on a new contract or in a new full-time position?

Image by stock.xchng user: forwardcom

Will Kelly is a technical writer and analyst based in the Washington, DC area. His writing experience also includes writing technology articles for CNET TechRepublic and other sites. Will’s technology interests include collaboration platforms, enterprise mobility, Bring Your Own Device (BYOD), project management applications, and big data.


Originally published at willkelly.org on November 13, 2011.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.