<title> What Technical Writers Want You to Know </title>

This is a guide on how to work with the technical writing teams, whatever your role in the organization.

Your technical writing team is on a never-ending mission to gather, organize, and present information for diverse readers. This is a challenge if, like me, you’re working on a team that creates documentation for enterprise developers. The team extends its expertise far beyond the common misconception that technical writers sit all day in a room and write. We gather information, keep track of the projects, we learn about new technologies, take notes, file bugs, and participate in many Sprint Reviews. We code our own publishing tools and develop prototypes, talk to dozens of developers, product owners, product managers, and end-users. When we write, it’s usually a smaller chunk of our time.

However, we cannot independently guarantee that what we write is always up-to-date and accurate: we need you to confirm the technical details. We need your knowledge. So, what should you do when technical writers ask you to do stuff? For example, to review a draft document or meet in person to explain something? Here are some tips.

1. Don’t correct grammar or punctuation. Just don’t do it! Because technical writers don’t edit your code either (ahem, but we might have to if the UI copy requires it). All jokes aside, if you are correcting grammar and punctuation you are distracted from your main task: assuring the draft you were sent is technically accurate. Besides, editors and proofreaders who are exceptionally skilled in written language will check the final draft before it’s published.

2. Pay attention to technical accuracy. When you get a draft for review, the best thing you can do is to check for technical accuracy. Verify that the facts are indeed correct for the software version the document is covering. Warn us if anything is expected to happen that would make the document outdated. If you are a Product Owner, make sure the business value of the feature is well presented in the draft, because that is your responsibility.

3. If you write your own drafts, keep them short and informative. Whether you enjoy writing documentation, or you’re writing it because you have to, just keep it simple. We benefit if the draft is brief, and has only the essential extra details. Start with writing an outline. Cover only the important technical information. Don’t write a novel. Be prepared, your draft will probably be rephrased and cut into snippets of knowledge that fit into the existing documentation.

4. Don’t forget that your tech writers might also be subject matter experts. Your technical writer team might have followed the development of the product for years. The team may be working in the Agile methodology and will be current with many other teams’ sprints. They have good knowledge about the features. You can benefit from meeting with the technical writers in your company. However, these meetings may be a bit frustrating, because documentation can expose hidden complexities or poor user experience (but cannot fix them).

5. Keep in mind that documentation is part of the product. Everyone notices if documentation is missing or if it’s mediocre. Documentation improves usability and user-friendliness for some features, and sometimes it’s downright essential for product maintenance, and, well… use! The effort you expend when working with your technical writers results in documentation that increases the end-user productivity, and in the long run, profitability.

6. Appreciate the fact that you don’t have to write end-user documentation. If you’re a developer with end-users in mind (hopefully you are), you are lucky if you have a team of technical writers working alongside you. They take care of things like information architecture, conceptual information, task-based content, references, glossaries, and so on. That’s a lot of expertise if it’s to be done properly.

Even though you’re not writing documentation (you’re probably over the moon about that), that doesn’t mean you shouldn’t have a say in how it’s shaped. It’s a part of your feature. Your team expects you to challenge the documentation; in fact, we need your help. Poorly tested documentation hurts us all. Your specialized knowledge and context can contribute to increasing the quality of the documents the technical writing team produces. We are all working towards the same end goal: to provide our end users with the best experience. Let’s join forces!

Romeo is a Technical Writer, follow him on LinkedIn.