Why the Django Documentation Sucks

by Steve Holden

  • PSF chairman
  • Rambles


  • All documentation sucks because the mind of the writer can’t match the mind of the reader
  • Use cases mostly appear to be “I want to know about X”

Use cases

  • Documentation wasn’t necessarily done with use cases in mind

Images and pictures!

  • No pictures? A picture is worth a thousand words
  • Some people need visual pictures to process things - visual thinkers

No jokes?

  • Jokes cut through barriers and allow people to interact more intimately
  • Humor negates fear
  • But you run the risk of looking silly

Problem: overview

Problem: Tutorial

  • Put your apps in project subdirectories
  • It’s like they’d never heard of the Python PATH
  • manage.py startapp still does it that way.

Problem: SEO optimization

  • Why isn’t the first Google hit on every ‘django’ somewhere in the docs
  • Problem: Curious noob gets odd things
  • django users doesn’t return good results

Problem: People might get smug about Django docs

  • Because they have become smug


  • Make documentation submissions process easier
  • Ask for all doc submissions and reserve the right to edit