Writing Assistance, Inc.

Why Developers Write Horrible Documentation

by Jacquie Samuels

Image for Why Developers Write Horrible Documentation

The world of software development can be very fast paced and sometimes involves a mad scramble to get everything ready for release. Unless a company has an established process or department for technical documentation, it’s often the case that developers are asked to write the product documentation. After all, who knows the products as well as they do?

Even an established company can end up with developer-written documentation. For example, a certain software development company, usually very good at funneling content through their Documentation department, ended up with a small, quick project that was so ad hoc that no one ever even thought to say “You’d better tell the Documentation group that you’re working on this new product because, you know, clients sort of like documentation when you sell them a product. The day before release, they finally clued in and sent some content they’d developed on their own to be briefly reviewed by a technical writer (yes, that writer was me) to fix formatting, spelling, and grammatical errors—there wasn’t time for anything else. Off it went to the client.

The client spent three days with the product before saying “You know how we were saying we wanted the product right now? Well, we’d like you to spend some time writing more documentation before we’ll take it.” Yes, that’s right, they sent the product back because the documentation was bad.

What made that documentation bad? The developers who wrote it knew the product very well, they had (fairly) good command of the English language, and the product itself was not that complicated. So what went wrong?

The answer is not that developers don’t write well or can’t write documentation. They certainly could…if they weren’t developing that product. The problem is that developers are too close to their product. Don’t get me wrong; this is a very good thing. If the developers weren’t that close, the product would be horrible, half-built, and quasi-functional. However, developers just can’t have the viewpoint that’s needed for good documentation—content that is written from the user’s perspective, takes the user’s point of view, and strips away inadvertent assumptions a developer can make.

A big shift needs to occur when writing usable content. A developer’s viewpoint when writing documentation is “this is my product; here’s how to use its features”. A technical writer, however, creates content thinking “hello user, here is how you’ll be doing the things you want to do with this product.”

So it’s not the person that is at fault; it’s the role. Technical documentation requires a certain user-centric focus that is just not possible when you’ve been up to your neck in code for the weeks, months, or years. It’s just an added bonus that technical writers have also spent years perfecting tools, language skills, and techniques to create quality documentation with ease.

About the Author

Jacquie Samuels is a technical communication consultant providing companies with DITA, CMS, and information architecture solutions and training. She endeavors to help everyone create documentation that is stronger, faster, and smarter. You can connect with Jacquie through Writing Assistance, Inc. at www.writingassist.com or by email through sales@writingassist.com

Related Topics