Writing great documentation - CodeConf 2011 (original) (raw)

• 1.
• 3.
• 4.
  In Search ofLost Time 1,500,000 Infinite Jest 484,000 Django 360,000 New Testament 180,000 Your first manuscript 60,000
• 5.
  “The documentation andcommunity 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
• 6.
• 7.
  Why do peopleread documentation? Who should write documentation? What should we document? Which tools should we use?
• 8.
  Why do peopleread documentation? Who should write documentation? What should we document? Which tools should we use?
• 10.
• 11.
• 12.
  First contact -new users. Education - new & existing users. Support - experienced users.
• 13.
  First contact -new users. Education - new & existing users. Support - experienced users. Troubleshooting - annoyed users.
• 14.
  First contact -new users. Education - new & existing users. Support - experienced users. Troubleshooting - annoyed users. Internals - your fellow developers.
• 15.
  First contact -new users. Education - new & existing users. Support - experienced users. Troubleshooting - annoyed users. Internals - your fellow developers. Reference - everyone.
• 16.
• 17.
• 18.
  Why do peopleread documentation? Who should write documentation? What should we document? Which tools should we use?
• 19.
• 20.
• 21.
  “A great wayfor new contributors to get started with our project is to contribute documentation.”
• 22.
  1. Use awiki. 2. ...? 3. Great documentation!
• 23.
  A wiki tellsme that you don’t really care about your documentation. So why should I care about your software?
• 24.
• 25.
  “The code requiredto 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.”
• 26.
  “If the… patchadds a new feature, or modifies behavior of an existing feature, the patch should also contain documentation.”
• 27.
• 28.
  Why do peopleread documentation? Who should write documentation? What should we document? Which tools should we use?
• 29.
• 30.
  Tutorials Quick - anew 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.
• 31.
  Topic guides Conceptual -foster understanding, not parroting. Comprehensive - explain in detail. Tell me the why of the topic.
• 32.
• 33.
• 34.
• 35.
• 36.
• 37.
• 38.
• 39.
• 40.
• 41.
• 42.
  Documentation is fractal Inspiration: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…”
• 43.
  Why do peopleread documentation? Who should write documentation? What should we document? Which tools should we use?
• 44.
• 45.
• 46.
• 47.
• 51.
  Read the Docs Sign up Create, host, and browse documentation. or Log in Read the Docs What is this place? Read the Docs hosts documentation, making it fully searchable and easy to find. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar. It also supports webhooks so your docs get built when you commit code. There's 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. It's free and simple. Read Getting Started and find out how to host your docs on Read the Docs! Find a project Let's do this. Featured Projects Celery (asksol) View Docs
• 52.
• 55.
  Why do peopleread documentation? Who should write documentation? What should we document? Which tools should we use?
• 56.
• 57.
• 58.
• 59.
• 60.
• 61.