ApacheCon US 2008 Session

How Do You Do? Writing Documentation Your Audience Can Read

Documentation is often seen as the 'ugly sister' of open source work. Everyone knows they need it, but no one wants to write it. But writing documentation doesn't need to be a pain, and the advantages of having usable documentation are many. This talk will briefly introduce the need for documentation, and discuss the benefits that good documentation can bring to a software project. Then we'll go on to look at effective documentation from a variety of angles: knowing your audience and writing for them; helping users to find the information that they need within your documentation; writing clearly, and in a manner that people can read and understand with ease. Finally, the talk will cover some of the different types of documentation an open-source project needs: the different audiences that need to be addressed, and how to improve documentation overall by making things simpler, rather than trying to communicate everything at once.