6 ways to sabotage your technical documentation

markus-spiske-148030
Every job hunt and even unsolicited discussions with recruiters during the past few years brought me more tales of organizations continuing to have issues producing and maintaining technical documentation. It is not isolated in one sector, and I keep hearing the same problems repeatedly. This has been a real disappointment for me over the years I was a contract technical writer and now that I have a staff technical writer job.
 
Developing technical documentation isn’t fun. Otherwise, it wouldn’t be such an afterthought. Things aren’t made any easier with a technical writing profession that is fragmented on the actual role of the technical writer.
 
Here are some ways organizations sabotage their technical documentation:
 

 
  1. Depend on contractors too much. I am the first to agree that for many companies, the centralized technical documentation group deserved to die for many reasons. However, now the pendulum has swung the other way with too much dependence on contract technical writers to get the job done. If not managed properly, the potential to lose continuity when contract technical writers leave the project is great.

  2. Confuse technical writers with secretaries. A long simmering argument I’ve had with the technical writing profession is about whether technical writers need to understand what they are writing about. Without technical acumen, a technical writer has no business documenting technology, and the organization is at fault for hiring the person. Technical documentation worries can go away when a team has the right technical writer to create and manage their documents.

  3. Provide no feedback or reviews on documents. Even if you get a competent technical writer to work on your technical documentation, it is hard to escape review cycles especially if the project is running at a fast clip. Mind reading and technical writing aren’t synonymous.

  4. Deny technical documentation a seat at the table. The successful delivery of the technical documentation for a project means that a technical writer should have a place at the cross functional team’s table for meetings, design sessions, and scheduling. Hiring and positioning the right technical writer for your team means, they can shoulder the technical documentation worries and check in at milestones.

  5. Micromanage technical documentation. While micromanagement can hobble all elements of a project, a solo technical writer can get especially bogged down if a manager micromanages them through every task of their projects. The work of a technical writer may seem like an easy target especially on complex technology projects but micromanagement and constantly having to educate a manager on what is going on with technical documentation is a distraction that can sometimes drag down the entire effort.

  6. Build up artificial walls. When I have the opportunity, I am a big fan of working directly with programmers and engineers and avoid the artificial walls that separate the technical writer from the development team. My personal favorite is the non-technical manager who wants all technical questions to the developers to flow through them – I call it the “two tin cans and string” approach. A free flow of information is integral to the success of technical documentation efforts.
 
What other ways have you seen organizations sabotage their technical documentation?

Published by

Will Kelly

Will Kelly is a technical writer living and working in the Washington, DC area. After years of contracting, he returned to full-time corporate job in 2016. He writes thought leadership content around cloud, enterprise mobility, and cybersecurity topics. Will's has written for Samsung Business Insights, Tom's IT Pro, TechBeacon, CNET TechRepublic, and other sites. Earlier in his career, he wrote technical documentation for end users, developers, and operations teams. His current areas of interest include multi-cloud solutions, mobile security, and managed services. Follow Will on Twitter: @willkelly.

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s