Writing Docs: A beginners guide to writing documentation

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

A985c35d6be3c88a87d92b92b0d3756f?s=128

ericholscher

August 13, 2013
Tweet

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