writing great documentation - codeconf 2011
Post on 15-Jan-2015
6.233 Views
Preview:
DESCRIPTION
TRANSCRIPT
Writing Great Documentation
jacob@jacobian.org
66,000 lines of Python75,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?
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 documentationis 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.”
DocumentationDrivenDevelopment?
Why do people read documentation?
Who should write documentation?
What should we document?
Which tools should we use?
Tutorials
Topic guides
Reference
Troubleshooting
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.
Tutorials
Topic guides
Conceptual - foster understanding, not parroting.
Comprehensive - explain in detail.
Tell me the why of the topic.
Complete. Docs or it doesn’t exist.
Designed for experienced users.
Give me the how of the topic.
Reference
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
Tutorials Topic guides Reference Trouble-
shooting
ProjectTutorials,Getting started
Guides,How-tos
APIs,indexes,search
FAQs,KB
Document Introductory material
How-to guides
See also,next steps
Notes, warnings
Section Overview Tasks, examples
Cross-ref - other topics
Common pitfalls
Element Examples Detailed instructions
Cross-ref - API docs
“If it didn’t work…”
Inspiration: Jeff Osier-Mixon, Effectively Managing Documentation for Open Source Projects. http://bit.ly/g0PLFB
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.
Read the DocsRead the DocsCreate, host, and browse documentation.Create, host, and browse documentation.
Sign upSign up
or Log inLog in
Let's do this.Let's do this.
What is this place?What 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. There's also support for versioning so you can builddocs from tagged versions of your code in your repository. You can even create docs on the site. It's free andsimple. Read Getting Started and find out how to host your docs on Read the Docs!
Find a projectFind a project
Featured ProjectsFeatured Projects
Celery (asksol) View Docs
Read the Docshttp://readthedocs.org/
DoccoPyccoRocco
Shocco
Why do people read documentation?
Who should write documentation?
What should we document?
Which tools should we use?
Who should write documentation?
What should we document?
Which tools should we use?
Everyone reads documentation.
What should we document?
Which tools should we use?
Everyone reads documentation.
Developers write great documentation.
Which tools should we use?
Everyone reads documentation.
Developers write great documentation.
Great documentation is fractal.
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
top related