RTFM -- wRite The Friendly Manual

A session at DjangoCon US 2011

Thursday 8th September, 2011

2:20pm to 3:00pm

An introduction to writing great documentation. Not just in the "here's some tools and how to use them" sense, but in the "here's why you should care about documentation" sense and the "how to write things people will read" sense.

Sections 1-3 are intended to be short but sweet, introducing a few essential topics to set the stage for what comes after. Section 4 is where the real meat begins, covering some basic principles of actual writing. Sections 5-6 return to technical matters, with most of the focus being on overviews rather than in-depth tutorials on specific tools or services.

- The two kinds of documentation
1. Documentation for people who will hack on your code
2. Documentation for people will run your code
3. Why you need both!
4. Support mechanisms

- The other two kinds of documentation
1. Hand-written explanations
2. Auto-generated API references
3. Why you need both!
4. Support mechanisms

- The mindset
1. DDD - Document-Driven Development
2. Write documentation before code
3. Documentation as specification

- The style
1. "Raise your hand if you have a liberal-arts degree"
2. A whirlwind tour of good prose
3. Be friendly!
4. Writing to your audience
5. How to write a how-to

- The tools
1. reST
2. Sphinx
3. pydoc/epydoc/etc.
4. Django!

- The rest
1. What your file layout should look like
2. Magical distutils incantations
3. Hosting
- on your own
- on packages.python.org
- on readthedocs
- other options

- Feedback
1. Why "documentation" is a component in your issue tracker
2. How to handle suggestions gracefully

- Questions

About the speaker

This person is speaking at this event.
James Bennett

The thing that pegasizes. bio from Twitter

Coverage of this session

Sign in to add slides, notes or videos to this session

Tell your friends!


Time 2:20pm3:00pm PST

Date Thu 8th September 2011

Short URL


Official session page


View the schedule



Books by speaker

  • Practical Django Projects

See something wrong?

Report an issue with this session