Integrating technical writers into your development team can add a valuable new perspective to your team and to your projects. By virtue of their different background, experience, and education, technical writers may see project events differently from other team members. But gaining this perspective isn’t always easy. As a longtime technical writer, I am the first to say that a lot depends on the chemistry and trust between the technical writer and the team. Here are 10 things to keep in mind to get the most benefit from your technical documentation.

1: Your last technical writer was trying to lock you into a tool

Specialized technical writing tools, such as FrameMaker and Author-It, have their use cases. However, some technical writers use such tools to lock their employers or clients into a solution in hopes of preventing layoff or being fired before they want to leave the project.

When a technical writer wants to use one of these tools, look for a business case before purchasing. Undoubtedly, these tools have their merits, but make sure you have a backup on the team who knows the tool so your documents can move forward regardless of the writer.

2: The problem is you, not your last technical writer

Technical writers often get a bad rap and deservedly so in some circumstances. I’ve heard in many interviews, “Well, our last technical writer…” and then the interviewer regales me with tales of their technical documentation woes.

If you find yourself burning through technical writers, it’s time to reevaluate the technical writer job description, salary band/hourly rate, role on the team, and other project-related factors. The technical writer’s success depends on access to information, whether in the form of a development system, staff interviews, or the SharePoint sites holding your documentation. Do a post mortem of your previous technical writers and documentation and look for points where you can improve hiring or modify the role to position it for success.

3: Bugs in your code are like errors in the technical writer’s document

It’s easy to jump down on a typo or flaw in a technical writer’s document even when your Remedy ticket queue is brimming with software bug reports. Without a full-time editor, you still have options to put in another quality check for your documents, such as:

  • Include technical documentation as part of the overall quality assurance plan.
  • Have other project team members do a peer review of the technical documentation.
  • Use an iterative documentation development process, where the documentation is written in draft releases just as you release software.

4: The technical writer’s responsibility lies between the audience and the development team

Your technical writer actually serves two masters — your team and the audience for the documentation. You don’t have a double agent in your midst, but you can use this as a catalyst for discussion, especially if your technical writer has a body of work in your industry. If they have an analyst background, these writers can best serve the audience. Ignorance of technology or audience is never an asset for a technical writer.

5: Your product or system may be similar to a past project

Experienced technical writers, especially contractors, may have documented numerous systems of various types during their career. While the system you are building is new to you and your team, there is a chance that the technical writer may have documented something similar in the past.

You can use this to your team’s advantage by including technical writers in meetings and design sessions so they can use their base knowledge to learn your system. They can then ask questions to build the documentation and questions that may help elicit better ideas from the whole team.

6: Job security through obscurity can kill the technical writer

One of the worst offshoots of today’s economy is job security through obscurity. This is where team members or even entire teams hold onto vital project information in a misguided attempt to preserve their jobs. This attitude can sink technical writers and their documents. The only cure is to wire technical writers into your projects early on. This allows them to build relationships and learn the system on their own as much as feasible.

7: Planning is an important part of technical writing

Technical documentation, much less technical writers, can be seen as a luxury in these economically strapped times. Bringing in a technical writer in the later stages of a project can hamper the planning and upfront work that needs to take place to deliver documentation. Include your technical writers in project planning so they can help provide a feasible approach to delivering technical documentation in support of the project.

8: Technical writers can help you push back on unfeasible requirements

When technically unfeasible requirements arrive for a project, it can be daunting to teams that are a couple of layers removed from management. If you have a technical writer on your team, he or she can help you document and communicate the issues you have with the requirements to push back and gain a better outcome. Use a technical writer to create the audit trail you need to win such battles.

9: Technical writers have to ask questions end to end

Skilled technical writers are well versed in asking questions. They have the job of trying to write about a system end to end when your developers may know only their one component. It’s easy to think that they don’t need to know something, when it might be an opportunity to elicit a discussion between team members that can otherwise benefit the whole project. Properly framed questions from a technical writer can get people thinking and talking for the betterment of the project — but you have to work with the writer to take advantage of this talent.

10: Those documents really do need to be reviewed

Few people really enjoy documentation reviews. Even fewer managers make reviewers accountable for the reviews. This can hurt a technical writer’s success. To get around it, you have to get creative with running reviews, such as including incremental document reviews in your project plan, identifying the must-review sections for your over allocated staff, and raising the bar on technical accuracy for the writer.

Getting it right

A properly positioned technical writer can be a true asset for a development team. However, it takes the right writer, project management, and some planning to position your technical documentation for success.