Advent of Technical Writing: Being a Technical Writer

This is the final post in the Advent of Technical Writing series, wherein I will share something I have learned from my experience as a technical writer. My experience is primarily in software technical writing, but what you read may apply to different fields, too. View all posts in the series.

Over the last 24 days, we have covered multiple facets of technical writing. We covered how to prepare an outline for a technical document, write the first sentences of a document, how to structure your work, and more. We have discussed introductions, conclusions, and everything in between. I hope you have enjoyed the series as much as I have enjoyed writing it.

Technical writers should be, as I have discussed throughout this series, integrated throughout an organization. You may work with engineers, designers, product managers, a sales team, marketing, customers, and users throughout your journey.

Each member of your team has something they can offer to help you do your job. Engineers can help communicate the “hows” and “whys” behind technical decisions and ensure your documentation is comprehensive. Designers can help you with visual assets. Product managers, marketing, and sales can all assist with positioning.

Ultimately, technical writing is all about helping people learn. You will help people use software with best practices in mind, integrate your tools into their workflows, solve problems, debug issues, and learn new skills. Thinking about the potential to help people is one of my primary motivators for being a technical writer (alongside, admittedly, my penchant for detail when it comes to documentation!).

A lot of a technical writer’s time is spent writing, but there are other tasks that are equally important. Using products yourself. Getting to know best practices. Assisting with other team members. Perhaps you have additional marketing responsibiltiies, too. This may especially be the case at startups, such as the organization for whom I work (Roboflow). Notably, see yourself not just as a documentor, but an advocate for customers. Use what you learn in your role to suggest opportunities for improvement. How can SDKs be improved? How can you improve workflows to encourage people to write more documentation?

Empower others to write documentation, too. Encourage your team. Documentation doesn’t have to be intimidating. A few bullet points or paragraphs for new features written by engineers – or even a screencast – will go a long way, for example. While accuracy is crucial, there is no such thing as perfect documentation (and yes, just because you wrote it, that doesn’t mean it is perfect and not open for improvement!). Prioritize accuracy and comprehensiveness. Settle for good enough. Provide feedback to your team to help them become better writers. Edit work as necessary. Where possible, make sure your work is edited, too.

There is one tiny detail that I have wanted to mention throughout this series but have never had a place: use exclamation points sparingly. I like to use one in an introduction in blog posts; the enthusiasm matches my style. In product documentation and code documentation, I avoid them entirely. Let your writing speak for itself.

Remember the moments when people thank you for your documentation, no matter how common or far apart those moments are.

Being a technical writer may sound boring, but you have an important and specialist role: you communicate complex topics in language that a target audience can understand. Your work helps people use software, code, products, standards, and so many other things. As you go along, make sure you have time for fun activities. (For me, this is trying to sneak in the odd Taylor Swift reference in an exclusively marketing blog post. Yes, I’m a Swiftie. It’s on my homepage, and my Spotify Wrapped 2023.)

Should you have any more questions about technical writing, please email me at jamesg [at] jamesg [dot] blog. I may write more blog posts about this topic over time as I have inspiration.