Writing Docs: A beginners guide to writing documentation

This is a first attempt at a slide deck for beginners who are interested in writing documentation. The keynote source and other additions will live at the Write the Docs website: http://docs.writethedocs.org/en/latest/#contents

Transcript

1. Eric Holscher eric@ericholscher.com PDX Python August 13, 2013 Writing docs A beginners guide to writing documentation
2. What you should do • Stop me if anything is unclear • Ask questions
3. About me • Write the Docs • Read the Docs
4. What we’ll cover • Why write docs • What technology • What to write
5. Why Write Docs
6. You will be using your code in 6 months
7. You want people to use your code
8. You want people to help out
9. It makes your code better
10. You want a (better) community
11. You want to be a better writer
12. What Technology
13. Simple is best
14. Plain Text
15. Resources --------- * Online documentation: http://docs.writethedocs.org/ * Conference: http://conf.writethedocs.org/ Basic Example
16. Basic Example
17. Version Controlled
18. Canonical
19. README.md
20. markdowntutorial.com
21. Moving beyond a single file
22. docs/ with files
23. Sphinx See: http://write-the-docs.rtfd.org/sphinx
24. What to write See: write-the-docs.rtfd.org/oss
25. Who are you writing for?
26. What problem your project solves
27. Small code example
28. Major Features
29. Installation Instructions
30. Tutorial
31. Links to code and issues
32. Any other way to get support
33. A license! Reference: http://choosealicense.com/
34. Changelog
35. Cookbook*
36. Community Information*
37. Design Document*
38. Contributor information*
39. Conclusion • Why write docs • What technology • What to write
40. Resources • http://producingoss.com/en/getting- started.html • http://docs.writethedocs.org/ • http://jacobian.org/writing/great- documentation/
41. Interested? • Thinking about starting a doc meetup • groups.google.com/group/write-the-docs
42. This is a living document • It will be edited and live on • Other people can give this talk • Create an intermediate & advanced talk
43. Questions & Feedback • Here and now • eric@ericholscher.com • @ericholscher