Why software engineers should invest in technical writing

Published in

Jit Team

4 min readJul 4, 2022

At some point in a software engineer’s career comes a time when he or she has to write documentation to share knowledge with others.

Introduction

At some point in a software engineer’s career comes a time when he or she has to write documentation to share knowledge with others. The alacrity with which software developers do that is on the same or even lower plane as writing unit tests for their code. In other words, hardly ever does an engineer want to write a document despite the fact that documentation is crucial in every project. So, when push comes to shove, the engineers do write documentation but oftentimes what they produce leaves room for improvement. No wonder, since it is not their field of expertise. As a person whose job is to write documentation, I’ll share some good, reliable, and free resources you can find across the Internet.

Benefits of technical writing for engineers

There can be no company that scales without documentation and documentation culture. To save time and avoid directly explaining to each individual how a particular feature works, how to set up the development environment, how a new architectural design works, to mention a few — engineers should invest in honing their writing skills.

The skills of technical communication will set you apart from other engineers since you will provide more than engineering services alone. As you grow your engineering skills, it is in your and others’ best interest to share your knowledge. By tranfsering knowledge, you become a reputable expert in your field and achieve a great sense of acomplishment. While others can learn from you and grow as engineers themselves.

Since engineering tends to be complex, technical writing helps present information in a clear and concise manner. Devoting your time to learning the basics of technical writing will smooth operations within your company and will lower the learning curve for your stakeholders.

Earn money by writing articles

If the above-mentioned arguments didn’t convince you, maybe you will be persuaded by lucrative remuneration. There’s a lot of companies that pay engineers and technical writers for writing articles. Most of these companies pay $200 — $1000 for an article. Of course, each company has their own guidelines and requirements you will have to meet. However, the overarching technical writing principles remain the same across the board.

Neptune.ai
Vonage
Digital Ocean
Twilio
check out more companies here

List of tech writing courses

Google’s Technical Writing course — Google strongly believes that every engineer is also a writer and this is what I would want to emphasize. Anyways, Google’s course is divided into Technical Writing I and Technical Writing II. The course includes pre-class and in-class activities. For pre-class activities, you need to read the material. For in-class activities, you need to find a facilitator or can go through the facilitator’s guide yourself. Google occasionally provides free, in-class sessions open to the general public. They provide the schedule in this link, so make sure to check it every now and then.

GitLab’s Technical Writing Fundamentals — GitLab builds on Google’s Technical Writing I pre-class material. They cover more grammar and style requirements, linting, and explain the basic concepts of DITA’s content units — concepts, tasks, references, troubleshooting (CTRT). What GitLab also offers is a treasure trove of documented processes they use for writing documentation.

List of tech writing blogs

If you become swayed by the courses and want to learn more, I recommend the following blogs:

List of tech writing books

For more structured reading experience, I would recommend these books:

Information Architecture, 4th Edition by Louis Rosenfeld, Peter Morville, Jorge Arango, O’Reilly Media, Inc.
The Insider’s Guide to Technical Writing, Krista Van Laan
Managing Enterprise Content: A Unified Content Strategy, Ann Rockley
Modern Technical Writing: An Introduction to Software Documentation, Andrew Etter
The Product is Docs: Writing technical documentation in a product development group, Christopher Gales, Splunk Documentation Team
Docs Like Code, Anne Gentle
Content Design, Sarah Richards
Conversational Design, Erika Hall
Microcopy: The Complete Guide, Kinneret Yifrah
Managing Writers: A Real World Guide to Managing Technical Documentation, XML Press: Fort Collins (2009), Hamilton R
Handbook of Technical Writing (9th edition), St. Martin’s Press: Boston (2009), Alred G., Brushaw C., Oliu W.
Technical Writing: A Resource for Technical Writers at All Levels, Kaplan Publishing: New York (2008), Hannigan C. et al.
ISO/IEC 26514:2008(E), Systems and software engineering — Requirements for designers and developers of user documentation
Technical Writing 101: A Real-World Guide to Planning and Writing Technical Documentation, Alan S. Pringle, Sarah S. O’Keefe
Content Strategy 101, Alan S. Pringle, Sarah S. O’Keefe
The State of Structured Authoring (second edition), Alan S. Pringle, Sarah S. O’Keef
The DITA Style Guide: Best Practices for Authors, Tony Self

Conclusion

Writing for the uninitiated can be challenging at first but it grows on you. Both parties benefit from a well written text that is easy to follow and read. Engineers don’t have to spend additional time on calls to explain what they meant and can earn extra money by writing. Readers won’t be frustrated with unclear instructions and will feel a sense of accomplishment after successfully following a guide.