Overview

Docs for Devs is dedicated to helping software developers improve their technical writing.

Why You Should Improve Your Technical Writing Skills as a Developer

Most developers appreciate good documentation. And most don't write it.

Quality Documentation is Important and Needed

Quality documentation plays a key role in the successful adoption of developer focused products. In her article What is Developer Advocacy?, Ashley McNamara, principal developer advocate at Microsoft, writes that “documentation can make or break your product”.[1]

Documentation can make or break your product. When a developer is using your product for the first time, they’re going to start with the docs. If your “Getting Started” guides are not clear, then you’ll likely lose that user. Remember that this is one of the first experiences a developer will have with your product and, if you want them to stick around, on-boarding needs to be painless.

Similarly, Daniele Procida, community & documentation manager at Divio, says people don’t use poorly documented software.[2]

It doesn’t matter how good your software is, because if the documentation is not good enough, people will not use it.

Tom Preston-Werner, founder and former CEO of GitHub, encourages developers to write documentation first — before code. And he believes that a product without documentation is basically “worthless”.[3]

A perfect implementation of the wrong specification is worthless. By the same principle a beautifully crafted library with no documentation is also damn near worthless. If your software solves the wrong problem or nobody can figure out how to use it, there’s something very bad going on.

Documentation is essential for helping inexperienced developers learn and grow — it “helps orient newcomers”⁴.

Documentation helps orient newcomers: how to use a project, how to contribute back, the terms of use and contribution, and the standards of conduct in a community.

Poor Quality Documentation is a Hindrance

When documentation is incomplete or confusing, developers waste time searching for missing information or making avoidable mistakes. They are also more likely to have a negative experience with your product.

In a 2019 survey by Hacker Rank, “badly written documentation” was the number one “pet peeve” of junior developers and the third for senior developers. Similarly, “poor documentation” was the second most common workplace gripe in the 2016 Stack Overflow Developer Survey.

Good Technical Writing Will Give You an Edge

While developers do appreciate and benefit from quality documentation, most don’t write it.

Incomplete or outdated documentation is a pervasive problem, observed by 93% of respondents, yet 60% of contributors say they rarely or never contribute to documentation.[4]

Most developers either don't care or don't know how to write documentation. Their focus is on crafting software, not communicating about it to non-technical people.[5]

Improving your technical writing skills will give you a communication edge over your peers and allow you to better serve your organization.


[1] What is Developer Advocacy?
[2] What nobody tells you about documentation
[3] Readme Driven Development
[4] 2017 Open Source Survey
[5] How to Write Usable User Documentation, pg. 6-7, Edmond H. Weiss