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:
- 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.
- 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.
- 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.
- 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.
- 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.
- 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?
Will Kelly 
You must be logged in to post a comment.