Writing great documentation - CodeConf 2011
Upcoming SlideShare
Loading in...5
×
 

Writing great documentation - CodeConf 2011

on

  • 6,896 views

 

Statistics

Views

Total Views
6,896
Views on SlideShare
6,728
Embed Views
168

Actions

Likes
16
Downloads
119
Comments
1

5 Embeds 168

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

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
  • This is an outstanding slide deck. The typography is excellent, the content is excellent, and the length is perfect!

    Thank you so much!
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

Writing great documentation - CodeConf 2011 Writing great documentation - CodeConf 2011 Presentation Transcript

  • 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 180,000Your first 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, 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 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 alsoinclude a regression test to validate thebehavior that has been fixed.”
  • “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 easy - don’t sugar-coat the truth.Show off 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: 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…”
  • 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 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
  • 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 use good ones!
  • My goal:Documentation Culture.
  • Go. Write.jacob@jacobian.org