SlideShare a Scribd company logo
Writing Great
Documentation

  jacob@jacobian.org
Writing great documentation - CodeConf 2011
66,000 lines of Python
75,000 lines of English
In Search of Lost Time   1,500,000

Infinite Jest              484,000

Django                    360,000

New Testament             180,000

Your first manuscript       60,000
“The documentation and community are second to none.”


“[W]e’ve found that people …can get up-to-speed relatively
quickly thanks to the excellent documentation…”


“Django … provides an excellent developer experience, with
great documentation and tutorials…”


“Our initial choice … was based on the strength of the
Django community and documentation…”


“Productive development, good documentation, flexibility,
and it just works.”

                                            http://j.mp/hnOsVl
My goal:
Documentation
   Culture.
Why do people read documentation?

Who should write documentation?

What should we document?

Which tools should we use?
Why do people read documentation?

Who should write documentation?

What should we document?

Which tools should we use?
Writing great documentation - CodeConf 2011
First contact - new users.
First contact - new users.

Education - new & existing users.
First contact - new users.

Education - new & existing users.

Support - experienced users.
First contact - new users.

Education - new & existing users.

Support - experienced users.

Troubleshooting - annoyed users.
First contact - new users.

Education - new & existing users.

Support - experienced users.

Troubleshooting - annoyed users.

Internals - your fellow developers.
First contact - new users.

Education - new & existing users.

Support - experienced users.

Troubleshooting - annoyed users.

Internals - your fellow developers.

Reference - everyone.
Documentation is Communication.
Great documentation
has to serve multiple,
conflicting masters.
Why do people read documentation?

Who should write documentation?

What should we document?

Which tools should we use?
Anyone!
Anyone!
  But...
“A great way for new contributors to
get started with our project is to
contribute documentation.”
1. Use a wiki.

2. ...?

3. Great documentation!
A wiki tells me that you don’t really care
about your documentation.

So why should I care about
your software?
Great documentation
    is written by
 great developers.
“The code required to fix a problem… is an
essential part of a patch, but it is not the
only part. A good patch should also
include a regression test to validate the
behavior that has been fixed.”
“If the… patch adds a new feature, or
modifies behavior of an existing feature,
the patch should also contain
documentation.”
Documentation
Driven
Development?
Why do people read documentation?

Who should write documentation?

What should we document?

Which tools should we use?
Tutorials

Topic guides

Reference

Troubleshooting
Tutorials
Quick - a new user should experience
        success within 30 minutes.

Easy - help users feel epic win.

Not too easy - don’t sugar-coat the truth.

Show off how the project feels.
Topic guides

Conceptual - foster understanding,
             not parroting.

Comprehensive - explain in detail.

Tell me the why of the topic.
Reference

Complete. Docs or it doesn’t exist.

Designed for experienced users.

Give me the how of the topic.
Auto-generated reference
documentation is almost worthless.
There’s no substitute
  for documentation
 written, organized,
and edited by people.
Troubleshooting


Answers to questions asked in anger.

FAQs are great as long as the Qs are
really FA’d.
Great documentation
     is fractal
Tutorials

Topic guides

Reference

Troubleshooting
Project:
Tutorials, getting started.

Topic guides, How-to guides.

Reference material, APIs, indexes, search.

Troubleshooting guides, FAQs, KBs.
Document:
Introduction.

Overview guide.

Details, cross-references, next steps.

Notes, warnings.
Section:
Overview.

Tasks & examples.

Detailed descriptions.

Common pitfalls, warnings.
Element:
Examples.

Detailed instructions.

API documentation.

“If it didn’t work….”
Documentation is fractal
Inspiration: Jeff Osier-Mixon, Effectively Managing Documentation for Open Source Projects. http://bit.ly/g0PLFB


                                                   Topic                                 Trouble-
                            Tutorials                               Reference
                                                  guides                                 shooting

                            Tutorials,                                 APIs,
                                                 Guides,                                    FAQs,
        Project              Getting                                 indexes,
                                                 How-tos                                     KB
                             started                                  search

                         Introductory            How-to              See also,            Notes,
      Document
                           material              guides             next steps           warnings

                                                  Tasks,            Cross-ref -          Common
        Section            Overview
                                                examples           other topics           pitfalls

                                                Detailed            Cross-ref -         “If it didn’t
       Element             Examples
                                              instructions           API docs             work…”
Why do people read documentation?

Who should write documentation?

What should we document?

Which tools should we use?
Tools don’t matter.
Tools don’t matter.
     (For the most part.)
Text is best.

Aesthetics are important.

Discoverability is vital.
http://sphinx.pocoo.org/
Writing great documentation - CodeConf 2011
Writing great documentation - CodeConf 2011
Writing great documentation - CodeConf 2011
Read the Docs                                                                     Sign up
            Create, host, and browse documentation.
                                                                                             or Log in




                    Read the Docs
What is this place?
Read the Docs hosts documentation, making it fully searchable and easy to find. You can import your docs
using any major version control system, including Mercurial, Git, Subversion, and Bazaar. It also supports
webhooks so your docs get built when you commit code. There's also support for versioning so you can build

                            http://readthedocs.org/
docs from tagged versions of your code in your repository. You can even create docs on the site. It's free and
simple. Read Getting Started and find out how to host your docs on Read the Docs!




Find a project

                                                                                      Let's do this.




Featured Projects

  Celery (asksol)                                                                                View Docs
Docco
 Pycco
Rocco
Shocco
Writing great documentation - CodeConf 2011
Writing great documentation - CodeConf 2011
Why do people read documentation?

Who should write documentation?

What should we document?

Which tools should we use?
Everyone reads documentation.

Who should write documentation?

What should we document?

Which tools should we use?
Everyone reads documentation.

Developers write great documentation.

What should we document?

Which tools should we use?
Everyone reads documentation.

Developers write great documentation.

Great documentation is fractal.

Which tools should we use?
Everyone reads documentation.

Developers write great documentation.

Great documentation is fractal.

Tools don’t matter. But use good ones!
My goal:
Documentation
   Culture.
Go.
  Write.

jacob@jacobian.org

More Related Content

KEY
Django In The Real World
PDF
Unbreaking Your Django Application
PDF
Best Practices for Front-End Django Developers
PDF
Free django
PDF
Python & Django TTT
PPTX
django Forms in a Web API World
KEY
Web application development with Django framework
PPTX
Django app deployment in Azure By Saurabh Agarwal
Django In The Real World
Unbreaking Your Django Application
Best Practices for Front-End Django Developers
Free django
Python & Django TTT
django Forms in a Web API World
Web application development with Django framework
Django app deployment in Azure By Saurabh Agarwal

What's hot (20)

PDF
JavaScript-Core
PDF
Comparing Hot JavaScript Frameworks: AngularJS, Ember.js and React.js - Sprin...
PDF
Design patterns revisited with PHP 5.3
ODP
Ant User Guide
PPT
JBUG 11 - Django-The Web Framework For Perfectionists With Deadlines
PDF
UKLUG - Open The Toolbox - Tools for the Domino Developer
PDF
Organinzing Your PHP Projects (2010 Memphis PHP)
PPT
High Performance Ajax Applications
PPT
Django, What is it, Why is it cool?
PDF
The Solar Framework for PHP 5 (2010 Confoo)
PDF
Django Introduction & Tutorial
PPT
Introduction To Django
PDF
JavaScript Library Overview
PDF
Behaviour Driven Development con Behat & Drupal
PDF
iPhone Coding For Web Developers
PDF
Action-Domain-Responder: A Refinement of MVC
PDF
遇見 Ruby on Rails
PDF
#NoXML: Eliminating XML in Spring Projects - SpringOne 2GX 2015
PDF
Django Framework and Application Structure
JavaScript-Core
Comparing Hot JavaScript Frameworks: AngularJS, Ember.js and React.js - Sprin...
Design patterns revisited with PHP 5.3
Ant User Guide
JBUG 11 - Django-The Web Framework For Perfectionists With Deadlines
UKLUG - Open The Toolbox - Tools for the Domino Developer
Organinzing Your PHP Projects (2010 Memphis PHP)
High Performance Ajax Applications
Django, What is it, Why is it cool?
The Solar Framework for PHP 5 (2010 Confoo)
Django Introduction & Tutorial
Introduction To Django
JavaScript Library Overview
Behaviour Driven Development con Behat & Drupal
iPhone Coding For Web Developers
Action-Domain-Responder: A Refinement of MVC
遇見 Ruby on Rails
#NoXML: Eliminating XML in Spring Projects - SpringOne 2GX 2015
Django Framework and Application Structure
Ad

Viewers also liked (6)

PDF
Jenkins without Install
PDF
Going Native With The OSGi Service Layer - Sascha Zelzer
PDF
Telling stories through your commits - Lead Developer Conference 2016
ODP
Libvirt and bhyve under FreeBSD
PDF
Commit messages - Good practices
PDF
Protecting Source Code
Jenkins without Install
Going Native With The OSGi Service Layer - Sascha Zelzer
Telling stories through your commits - Lead Developer Conference 2016
Libvirt and bhyve under FreeBSD
Commit messages - Good practices
Protecting Source Code
Ad

Similar to Writing great documentation - CodeConf 2011 (20)

KEY
Writing Awesome Docs for Your Code
ODP
User Love and how to get it through good documentation
KEY
Killer Docs for Killer Devs
PPT
FSOSS - Enter the 4th Dimension: Documentation
PDF
The Developer Experience
PDF
Documentation: get it right! (ApacheCon EU 2009)
PDF
Docathon: How to write (good) documentation
KEY
Write a better FM
KEY
The Developer Experience
PPT
APIs And SDKs Breaking Into And Succeeding In A Specialty Market
PDF
Living documentation
PDF
Living Documentation (presentation)
PDF
Use a systematic and recursive process to create pdf.pdf
PDF
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
ODP
Documenting code yapceu2016
ODP
Documenting Code - Patterns and Anti-patterns - NLPW 2016
PDF
Passing the Joel Test in the PHP World (phpbnl10)
PPTX
Maintainable API Docs and Other Rainbow Colored Unicorns
PPTX
Creating and Maintaining an Open Source Library
KEY
Get ready for web3.0! Open up your app!
Writing Awesome Docs for Your Code
User Love and how to get it through good documentation
Killer Docs for Killer Devs
FSOSS - Enter the 4th Dimension: Documentation
The Developer Experience
Documentation: get it right! (ApacheCon EU 2009)
Docathon: How to write (good) documentation
Write a better FM
The Developer Experience
APIs And SDKs Breaking Into And Succeeding In A Specialty Market
Living documentation
Living Documentation (presentation)
Use a systematic and recursive process to create pdf.pdf
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
Documenting code yapceu2016
Documenting Code - Patterns and Anti-patterns - NLPW 2016
Passing the Joel Test in the PHP World (phpbnl10)
Maintainable API Docs and Other Rainbow Colored Unicorns
Creating and Maintaining an Open Source Library
Get ready for web3.0! Open up your app!

More from Jacob Kaplan-Moss (11)

PDF
Introduction To Django (Strange Loop 2011)
PDF
The Best (and Worst) of Django
KEY
What's new in Django 1.2?
PDF
Django Introduction, Dev in Rio 2009
PDF
Snakes on the Web
PDF
Building a web framework: Django's design decisions
PDF
Django in the Real World
PDF
State Of Django
PDF
Django - the first five years
PDF
A brief history of Django model syntax
PDF
Django Update (OSCON 2007)
Introduction To Django (Strange Loop 2011)
The Best (and Worst) of Django
What's new in Django 1.2?
Django Introduction, Dev in Rio 2009
Snakes on the Web
Building a web framework: Django's design decisions
Django in the Real World
State Of Django
Django - the first five years
A brief history of Django model syntax
Django Update (OSCON 2007)

Recently uploaded (20)

DOCX
The AUB Centre for AI in Media Proposal.docx
PDF
Per capita expenditure prediction using model stacking based on satellite ima...
PDF
Approach and Philosophy of On baking technology
PPTX
Spectroscopy.pptx food analysis technology
PDF
Network Security Unit 5.pdf for BCA BBA.
PPTX
Machine Learning_overview_presentation.pptx
PPTX
Big Data Technologies - Introduction.pptx
PPTX
Digital-Transformation-Roadmap-for-Companies.pptx
PDF
Building Integrated photovoltaic BIPV_UPV.pdf
PDF
Reach Out and Touch Someone: Haptics and Empathic Computing
PPT
Teaching material agriculture food technology
PDF
gpt5_lecture_notes_comprehensive_20250812015547.pdf
PDF
Architecting across the Boundaries of two Complex Domains - Healthcare & Tech...
PDF
cuic standard and advanced reporting.pdf
PDF
Diabetes mellitus diagnosis method based random forest with bat algorithm
PPTX
KOM of Painting work and Equipment Insulation REV00 update 25-dec.pptx
PDF
Dropbox Q2 2025 Financial Results & Investor Presentation
PPT
“AI and Expert System Decision Support & Business Intelligence Systems”
PDF
Review of recent advances in non-invasive hemoglobin estimation
PPTX
20250228 LYD VKU AI Blended-Learning.pptx
The AUB Centre for AI in Media Proposal.docx
Per capita expenditure prediction using model stacking based on satellite ima...
Approach and Philosophy of On baking technology
Spectroscopy.pptx food analysis technology
Network Security Unit 5.pdf for BCA BBA.
Machine Learning_overview_presentation.pptx
Big Data Technologies - Introduction.pptx
Digital-Transformation-Roadmap-for-Companies.pptx
Building Integrated photovoltaic BIPV_UPV.pdf
Reach Out and Touch Someone: Haptics and Empathic Computing
Teaching material agriculture food technology
gpt5_lecture_notes_comprehensive_20250812015547.pdf
Architecting across the Boundaries of two Complex Domains - Healthcare & Tech...
cuic standard and advanced reporting.pdf
Diabetes mellitus diagnosis method based random forest with bat algorithm
KOM of Painting work and Equipment Insulation REV00 update 25-dec.pptx
Dropbox Q2 2025 Financial Results & Investor Presentation
“AI and Expert System Decision Support & Business Intelligence Systems”
Review of recent advances in non-invasive hemoglobin estimation
20250228 LYD VKU AI Blended-Learning.pptx

Writing great documentation - CodeConf 2011