Contribute Media
A thank you to everyone who has made this possible: Read More

How documentation works, and how to make it work for your project


Nearly everyone (especially in the Python community) agrees that good documentation is important to the success of software projects, and yet very few projects actually have good documentation.

Often, it's not for want of effort - the project's developers have worked hard on it - nor for lack of documentation - the authors have produced a lot of it.

It simply turns out to be not very good - not helpful enough for the users who should be able to rely on it, and a depressing chore for the authors who have to maintain it.

The good news is that both these problems can be solved by understanding how documentation works, and what its different functions are. Structuring documentation according to those distinct functions helps ensure that each of them is adequately served. It also makes it far easier to write and maintain.

Using real-life examples I'll draw out the key functions of documentation, and how they map onto different ways of writing it. Putting this into practice is simple when armed with some basic guidelines. The benefits are huge, and available with a minimum of effort.

I won't be discussing documentation tools or software or other topics that have been covered amply elsewhere, but some neglected aspects of software documentation that will make your software projects more successful.


Improve this page