Your SlideShare is downloading. ×
0
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
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
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
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
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
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
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
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
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
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Writing great documentation - CodeConf 2011

6,550

Published on

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

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 1. Writing GreatDocumentation jacob@jacobian.org
  • 2. 66,000 lines of Python75,000 lines of English
  • 3. In Search of Lost Time 1,500,000Infinite Jest 484,000Django 360,000New Testament 180,000Your first manuscript 60,000
  • 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. 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 documentationhas 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 toget started with our project is tocontribute documentation.”
  • 20. 1. Use a wiki.2. ...?3. Great documentation!
  • 21. A wiki tells me that you don’t really careabout your documentation.So why should I care aboutyour software?
  • 22. Great documentation is written by great developers.
  • 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. “If the… patch adds a new feature, ormodifies behavior of an existing feature,the patch should also containdocumentation.”
  • 25. DocumentationDrivenDevelopment?
  • 26. Why do people read documentation?Who should write documentation?What should we document?Which tools should we use?
  • 27. TutorialsTopic guidesReferenceTroubleshooting
  • 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. Topic guidesConceptual - foster understanding, not parroting.Comprehensive - explain in detail.Tell me the why of the topic.
  • 30. ReferenceComplete. Docs or it doesn’t exist.Designed for experienced users.Give me the how of the topic.
  • 31. Auto-generated referencedocumentation is almost worthless.
  • 32. There’s no substitute for documentation written, organized,and edited by people.
  • 33. TroubleshootingAnswers to questions asked in anger.FAQs are great as long as the Qs arereally FA’d.
  • 34. Great documentation is fractal
  • 35. TutorialsTopic guidesReferenceTroubleshooting
  • 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 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. 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 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. Docco PyccoRoccoShocco
  • 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

×