Writing GreatDocumentation  jacob@jacobian.org
66,000 lines of Python75,000 lines of English
In Search of Lost Time   1,500,000Infinite Jest              484,000Django                    360,000New Testament         ...
“The documentation and community are second to none.”“[W]e’ve found that people …can get up-to-speed relativelyquickly tha...
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.Int...
First contact - new users.Education - new & existing users.Support - experienced users.Troubleshooting - annoyed users.Int...
Documentation is Communication.
Great documentationhas 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 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 fix a problem… is anessential part of a patch, but it is not theonly part. A good patch should alsoin...
“If the… patch adds a new feature, ormodifies behavior of an existing feature,the patch should also containdocumentation.”
DocumentationDrivenDevelopment?
Why do people read documentation?Who should write documentation?What should we document?Which tools should we use?
TutorialsTopic guidesReferenceTroubleshooting
TutorialsQuick - a new user should experience        success within 30 minutes.Easy - help users feel epic win.Not too eas...
Topic guidesConceptual - foster understanding,             not parroting.Comprehensive - explain in detail.Tell me the why...
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 g...
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: Jeff Osier-Mixon, Effectively Managing Documentation for Open Source Projects. http://b...
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/
Read the Docs                                                                     Sign up            Create, host, and bro...
Docco PyccoRoccoShocco
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 u...
My goal:Documentation   Culture.
Go.  Write.jacob@jacobian.org
Writing great documentation - CodeConf 2011
Writing great documentation - CodeConf 2011
Writing great documentation - CodeConf 2011
Writing great documentation - CodeConf 2011
Writing great documentation - CodeConf 2011
Writing great documentation - CodeConf 2011
Writing great documentation - CodeConf 2011
Upcoming SlideShare
Loading in...5
×

Writing great documentation - CodeConf 2011

6,631

Published on

Published in: Technology
1 Comment
19 Likes
Statistics
Notes
No Downloads
Views
Total Views
6,631
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
126
Comments
1
Likes
19
Embeds 0
No embeds

No notes for slide

Transcript of "Writing great documentation - CodeConf 2011"

  1. 1. Writing GreatDocumentation jacob@jacobian.org
  2. 2. 66,000 lines of Python75,000 lines of English
  3. 3. In Search of Lost Time 1,500,000Infinite Jest 484,000Django 360,000New Testament 180,000Your first manuscript 60,000
  4. 4. “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, flexibility,and it just works.” http://j.mp/hnOsVl
  5. 5. My goal:Documentation Culture.
  6. 6. Why do people read documentation?Who should write documentation?What should we document?Which tools should we use?
  7. 7. Why do people read documentation?Who should write documentation?What should we document?Which tools should we use?
  8. 8. First contact - new users.
  9. 9. First contact - new users.Education - new & existing users.
  10. 10. First contact - new users.Education - new & existing users.Support - experienced users.
  11. 11. First contact - new users.Education - new & existing users.Support - experienced users.Troubleshooting - annoyed users.
  12. 12. First contact - new users.Education - new & existing users.Support - experienced users.Troubleshooting - annoyed users.Internals - your fellow developers.
  13. 13. First contact - new users.Education - new & existing users.Support - experienced users.Troubleshooting - annoyed users.Internals - your fellow developers.Reference - everyone.
  14. 14. Documentation is Communication.
  15. 15. Great documentationhas to serve multiple,conflicting masters.
  16. 16. Why do people read documentation?Who should write documentation?What should we document?Which tools should we use?
  17. 17. Anyone!
  18. 18. Anyone! But...
  19. 19. “A great way for new contributors toget started with our project is tocontribute documentation.”
  20. 20. 1. Use a wiki.2. ...?3. Great documentation!
  21. 21. A wiki tells me that you don’t really careabout your documentation.So why should I care aboutyour software?
  22. 22. Great documentation is written by great developers.
  23. 23. “The code required to fix 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 fixed.”
  24. 24. “If the… patch adds a new feature, ormodifies behavior of an existing feature,the patch should also containdocumentation.”
  25. 25. DocumentationDrivenDevelopment?
  26. 26. Why do people read documentation?Who should write documentation?What should we document?Which tools should we use?
  27. 27. TutorialsTopic guidesReferenceTroubleshooting
  28. 28. 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 off how the project feels.
  29. 29. Topic guidesConceptual - foster understanding, not parroting.Comprehensive - explain in detail.Tell me the why of the topic.
  30. 30. ReferenceComplete. Docs or it doesn’t exist.Designed for experienced users.Give me the how of the topic.
  31. 31. Auto-generated referencedocumentation is almost worthless.
  32. 32. There’s no substitute for documentation written, organized,and edited by people.
  33. 33. TroubleshootingAnswers to questions asked in anger.FAQs are great as long as the Qs arereally FA’d.
  34. 34. Great documentation is fractal
  35. 35. TutorialsTopic guidesReferenceTroubleshooting
  36. 36. Project:Tutorials, getting started.Topic guides, How-to guides.Reference material, APIs, indexes, search.Troubleshooting guides, FAQs, KBs.
  37. 37. Document:Introduction.Overview guide.Details, cross-references, next steps.Notes, warnings.
  38. 38. Section:Overview.Tasks & examples.Detailed descriptions.Common pitfalls, warnings.
  39. 39. Element:Examples.Detailed instructions.API documentation.“If it didn’t work….”
  40. 40. Documentation is fractalInspiration: 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. 41. Why do people read documentation?Who should write documentation?What should we document?Which tools should we use?
  42. 42. Tools don’t matter.
  43. 43. Tools don’t matter. (For the most part.)
  44. 44. Text is best.Aesthetics are important.Discoverability is vital.
  45. 45. http://sphinx.pocoo.org/
  46. 46. 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
  47. 47. Docco PyccoRoccoShocco
  48. 48. Why do people read documentation?Who should write documentation?What should we document?Which tools should we use?
  49. 49. Everyone reads documentation.Who should write documentation?What should we document?Which tools should we use?
  50. 50. Everyone reads documentation.Developers write great documentation.What should we document?Which tools should we use?
  51. 51. Everyone reads documentation.Developers write great documentation.Great documentation is fractal.Which tools should we use?
  52. 52. Everyone reads documentation.Developers write great documentation.Great documentation is fractal.Tools don’t matter. But use good ones!
  53. 53. My goal:Documentation Culture.
  54. 54. Go. Write.jacob@jacobian.org
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×