Jit Team
Published in

Jit Team

Why software engineers should invest in technical writing

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.

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.

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.

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.

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.

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

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

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.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store