Saturday 11:30 a.m.–noon

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

Daniele Procida


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**.