Leadership

10 things you should know about working with technical writers

Good technical writers can be an asset to your team, but only if you know how to take advantage of their perspective and insights.

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.

About

Will Kelly is a freelance technical writer and analyst currently focusing on enterprise mobility, Bring Your Own Device (BYOD), and the consumerization of IT. He has also written about cloud computing, Big Data, virtualization, project management ap...

4 comments
dltkkennedy
dltkkennedy

After 30 years, I retired from two of Eaton Corporation's plants in WI as a Sr. Technical Writer. To be successful, I worked closly with engineers & assembly areas in the factory. David Kennedy, Adams, WI

GrizzledGeezer
GrizzledGeezer

...it's an absolute necessity. It keeps the customers happy and reduces support costs. The writer needs time to learn the product well because, without close knowledge, he can't do a good job. Hiring a writer at the last minute is not only cheap, but an insult. High-quality documentation takes time. It can't be thrown together at the last minute.

blein
blein

I used to be one-removed from the Tech Writer. I developed training for the user on the software product. We too, need to be in the loop. I test each "lesson" and can find "bugs" in the software AND in the documentation. On a complex software product I discovered a problem when I tested my training materials with 12 simultaneous users. The system froze! It was discovered (much later) that each software developer had both a client and a server on their system while testing -- they didn't notice that the software couldn't run with a single server and multiple clients ! Pet peeve: Too many User Guides simply state, "The Widget button sets the Widget." without describing the result of "setting of Widget" or in what situations you would want to do that.

TsarNikky
TsarNikky

Make the Technical Writer part of the team and have them become the first "user" of your new project. The writer represents a fresh set of "uncontaminated" eyes on how your projects looks and feels to potential users. The writer can be an excellent source of finding bugs and awkward/convoluted interaction paths. If your company writes several applications for the public, the Technical Writer can help ensure a consistent "look and feel" amongst all of your applications.

Editor's Picks