1.
Writing Great
Documentation
jacob@jacobian.org

2.
66,000 lines of Python
75,000 lines of English

3.
In Search of Lost Time 1,500,000
Infinite Jest 484,000
Django 360,000
New Testament 180,000
Your first manuscript 60,000

4.
“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

5.
My goal:
Documentation
Culture.

6.
Why do people read documentation?
Who should write documentation?
What should we document?
Which tools should we use?

7.
Why do people read documentation?
Who should write documentation?
What should we document?
Which tools should we use?

8.
First contact - new users.

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

10.
First contact - new users.
Education - new & existing users.
Support - experienced users.

11.
First contact - new users.
Education - new & existing users.
Support - experienced users.
Troubleshooting - annoyed users.

12.
First contact - new users.
Education - new & existing users.
Support - experienced users.
Troubleshooting - annoyed users.
Internals - your fellow developers.

13.
First contact - new users.
Education - new & existing users.
Support - experienced users.
Troubleshooting - annoyed users.
Internals - your fellow developers.
Reference - everyone.

14.
Documentation is Communication.

15.
Great documentation
has to serve multiple,
conflicting masters.

16.
Why do people read documentation?
Who should write documentation?
What should we document?
Which tools should we use?

17.
Anyone!

18.
Anyone!
But...

19.
“A great way for new contributors to
get started with our project is to
contribute documentation.”

20.
1. Use a wiki.
2. ...?
3. Great documentation!

21.
A wiki tells me that you don’t really care
about your documentation.
So why should I care about
your software?

22.
Great documentation
is written by
great developers.

23.
“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.”

24.
“If the… patch adds a new feature, or
modifies behavior of an existing feature,
the patch should also contain
documentation.”

25.
Documentation
Driven
Development?

26.
Why do people read documentation?
Who should write documentation?
What should we document?
Which tools should we use?

27.
Tutorials
Topic guides
Reference
Troubleshooting

28.
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.

29.
Topic guides
Conceptual - foster understanding,
not parroting.
Comprehensive - explain in detail.
Tell me the why of the topic.

30.
Reference
Complete. Docs or it doesn’t exist.
Designed for experienced users.
Give me the how of the topic.

31.
Auto-generated reference
documentation is almost worthless.

32.
There’s no substitute
for documentation
written, organized,
and edited by people.

33.
Troubleshooting
Answers to questions asked in anger.
FAQs are great as long as the Qs are
really FA’d.

34.
Great documentation
is fractal

35.
Tutorials
Topic guides
Reference
Troubleshooting

36.
Project:
Tutorials, getting started.
Topic guides, How-to guides.
Reference material, APIs, indexes, search.
Troubleshooting guides, FAQs, KBs.

37.
Document:
Introduction.
Overview guide.
Details, cross-references, next steps.
Notes, warnings.

38.
Section:
Overview.
Tasks & examples.
Detailed descriptions.
Common pitfalls, warnings.

39.
Element:
Examples.
Detailed instructions.
API documentation.
“If it didn’t work….”

40.
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…”

41.
Why do people read documentation?
Who should write documentation?
What should we document?
Which tools should we use?

42.
Tools don’t matter.

43.
Tools don’t matter.
(For the most part.)

44.
Text is best.
Aesthetics are important.
Discoverability is vital.

45.
http://sphinx.pocoo.org/

46.
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

47.
Docco
Pycco
Rocco
Shocco

48.
Why do people read documentation?
Who should write documentation?
What should we document?
Which tools should we use?

49.
Everyone reads documentation.
Who should write documentation?
What should we document?
Which tools should we use?

50.
Everyone reads documentation.
Developers write great documentation.
What should we document?
Which tools should we use?

51.
Everyone reads documentation.
Developers write great documentation.
Great documentation is fractal.
Which tools should we use?

52.
Everyone reads documentation.
Developers write great documentation.
Great documentation is fractal.
Tools don’t matter. But use good ones!

53.
My goal:
Documentation
Culture.

54.
Go.
Write.
jacob@jacobian.org