Why the Django Documentation Sucks¶
by Steve Holden
- PSF chairman
- Rambles
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¶
google “django overview” https://docs.djangoproject.com/en/dev/intro/overview/
- shouldn’t a glance be visual?
- Gigantic document
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
Solutions¶
- Make documentation submissions process easier
- Ask for all doc submissions and reserve the right to edit