Presentation: Write the Docs

Friday 5:10 p.m.–5:40 p.m.

Write the Docs

James Bennett

Audience level:: Novice
Category:: Documentation

Description

The greatest piece of software in the world is useless without great documentation, but unfortunately most of us just don't write great docs. This can be fixed, though. Documentation doesn't need to be an afterthought, and doesn't have to be bad, and you, too, can learn how to write good docs and make that an integrated part of your development process.

Abstract

This is not a talk about tools for generating or formatting or hosting documentation; there are enough of those already. Rather, it's a talk about three things:

Why good documentation is important. Not just "you should write documentation", but the benefits of having good documentation available (easier for all users, easier to acquire new users, easier to gain contributors on open-source projects).
How to make documentation part of your development process. Too often, documentation is an afterthought, if that. Instead, it should be a required part of developing new code, and ideally should be written up-front as part of initial design, and the code should later be checked against it.
Most important: how to write good, effective documentation. Though most of us are good at writing code, writing prose intended for others to read is more difficult. This will cover some basic principles for good writing, and for ensuring your documentation has the necessary reach to aid all of your users.