Download as PDF, PPTX
![“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](https://image.slidesharecdn.com/writinggreatdocumentation-codeconf2011-110409122301-phpapp02/85/Writing-great-documentation-CodeConf-2011-5-320.jpg)
More Related Content
Similar to Writing great documentation - CodeConf 2011
Writing great documentation - CodeConf 2011
- 1. Writing Great Documentation jacob@jacobian.org
- 3. 66,000 lines ofPython 75,000 lines of English
- 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. My goal: Documentation Culture.
- 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. First contact -new users.
- 11. First contact -new users. Education - new & existing users.
- 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. Great documentation has toserve multiple, conflicting masters.
- 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. Great documentation is written by great developers.
- 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. Reference Complete. Docs orit doesn’t exist. Designed for experienced users. Give me the how of the topic.
- 33. Auto-generated reference documentation isalmost worthless.
- 34. There’s no substitute for documentation written, organized, and edited by people.
- 35. Troubleshooting Answers to questionsasked in anger. FAQs are great as long as the Qs are really FA’d.
- 36. Great documentation is fractal
- 37.
- 38. Project: Tutorials, getting started. Topicguides, How-to guides. Reference material, APIs, indexes, search. Troubleshooting guides, FAQs, KBs.
- 39. Document: Introduction. Overview guide. Details, cross-references,next steps. Notes, warnings.
- 40. Section: Overview. Tasks & examples. Detaileddescriptions. Common pitfalls, warnings.
- 41. Element: Examples. Detailed instructions. API documentation. “Ifit didn’t work….”
- 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. Tools don’t matter. (For the most part.)
- 46. Text is best. Aestheticsare important. Discoverability is vital.
- 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. Everyone reads documentation. Whoshould write documentation? What should we document? Which tools should we use?
- 57. Everyone reads documentation. Developerswrite great documentation. What should we document? Which tools should we use?
- 58. Everyone reads documentation. Developerswrite great documentation. Great documentation is fractal. Which tools should we use?
- 59. Everyone reads documentation. Developerswrite great documentation. Great documentation is fractal. Tools don’t matter. But use good ones!
- 60. My goal: Documentation Culture.
- 61.