Writing great documentation - CodeConf 2011

Writing GreatDocumentation jacob@jacobian.org

66,000 lines of Python75,000 lines of English

In Search of Lost Time 1,500,000Inﬁnite Jest 484,000Django 360,000New Testament 180,000Your ﬁrst manuscript 60,000

“The documentation and community are second to none.”“[W]e’ve found that people …can get up-to-speed relativelyquickly thanks to the excellent documentation…”“Django … provides an excellent developer experience, withgreat documentation and tutorials…”“Our initial choice … was based on the strength of theDjango community and documentation…”“Productive development, good documentation, ﬂexibility,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?

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 documentationhas to serve multiple,conflicting masters.

Anyone!

Anyone! But...

“A great way for new contributors toget started with our project is tocontribute documentation.”

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

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

Great documentation is written by great developers.

“The code required to ﬁx a problem… is anessential part of a patch, but it is not theonly part. A good patch should alsoinclude a regression test to validate thebehavior that has been ﬁxed.”

“If the… patch adds a new feature, ormodiﬁes behavior of an existing feature,the patch should also containdocumentation.”

DocumentationDrivenDevelopment?

TutorialsTopic guidesReferenceTroubleshooting

TutorialsQuick - 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 oﬀ how the project feels.

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

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

Auto-generated referencedocumentation is almost worthless.

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

TroubleshootingAnswers to questions asked in anger.FAQs are great as long as the Qs arereally FA’d.

Great documentation is fractal

TutorialsTopic guidesReferenceTroubleshooting

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 fractalInspiration: Jeﬀ Osier-Mixon, Eﬀectively 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…”

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/

Read the Docs Sign up Create, host, and browse documentation. or Log in Read the DocsWhat is this place?Read the Docs hosts documentation, making it fully searchable and easy to find. You can import your docsusing any major version control system, including Mercurial, Git, Subversion, and Bazaar. It also supportswebhooks so your docs get built when you commit code. Theres 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. Its free andsimple. Read Getting Started and find out how to host your docs on Read the Docs!Find a project Lets do this.Featured Projects Celery (asksol) View Docs

Docco PyccoRoccoShocco

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

http://lanyrd.com	159
http://twitter.com	3
https://p.yammer.com	1
http://paper.li	1
https://twitter.com	1

Writing great documentation - CodeConf 2011

by Jacob Kaplan-Moss on Apr 09, 2011

Accessibility

Categories

Upload Details

Usage Rights

5 Embeds 165

Statistics

Writing great documentation - CodeConf 2011 Presentation Transcript