tychoish, a wiki

tychoish/technical-writing/ Why the Documentation Sucks

Why the Documentation Sucks

For many software projects and products, the documentation sucks. The resources are incomplete, out of date, hard to understand, or don't answer users' real questions. Perhaps the documentation doesn't always suck, but there's almost always room for improvement. Documentation--like the technology it supports--is always changing and this presents a host of unique challenges for those of us who maintain documentation.

This page collects a number of recurring problems with documentation, and presents tactics for improving documentation.

Problems with Documentation

Making Documentation Better

Some solutions to tactical problems presented above are addressed inline. Other, more global ways to address these issues include: