Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Documentation for Fun and Profit

C014b3eefe1f75efc7acfc0414d67795?s=47 James Aitken
November 24, 2012

Documentation for Fun and Profit

Good documentation is vital in helping others understand what your code does, why, and how they should use it.

I want to show you how to produce beautiful documentation, write better copy, and how documentation helps market your code.


James Aitken

November 24, 2012


  1. Documentation for fun and profit

  2. James Aitken UI/UX Team Leader – UK2Group @LoonyPandora

  3. You need good documentation

  4. But hate writing it…

  5. CHEAT!

  6. What is documentation?

  7. Code Comments?

  8. PyDoc RDoc TomDoc Docco Rocco Pycco PHPDoc JavaDoc YARD Doxygen

    JSDoc Epydoc CSSDoc KSS StyleDoc Other Languages
  9. Not in Perl

  10. Documentation = High Level =head2 validate_email This method determines whether

    an email address is valid or not
  11. Comments = Low Level # Use a naive regex to

    check emails # because I hate maintenance devs sub validate_email {
  12. None
  13. POD Plain Old Documentation

  14. Markup language, like HTML

  15. POD Sucks

  16. POD Sucks (On Purpose)

  17. “The intent is simplicity of use, not power of expression”

  18. POD is everywhere

  19. STEP 1 Know your audience

  20. What is good documentation

  21. Good Docs Must Be Clear Complete Concise

  22. Good Docs Answer Input Output Errors

  23. Missing one thing…

  24. Keep the docs up to date!

  25. Laziness Impatience Hubris

  26. “I’ll write the docs up tomorrow” everyone

  27. “Too much to do. Docs can wait” everyone

  28. “The code is self-explanatory” everyone

  29. MORE CODE!

  30. “Why is the documentation segfaulting?” future you


  32. “The intent is simplicity of use, not power of expression”

  33. CHEAT!

  34. Documentation needs a killer feature

  35. None
  36. “I thought it was pointless at first, but now I

    can’t live without it” colleague
  37. 82.4%* of people read POD unparsed * made up statistic

  38. Like coding without ‘strict’ on

  39. Readable docs = Useful docs

  40. We’re engineers, not designers…

  41. None
  42. CHEAT!

  43. POD::HTML5::Browser

  44. POD::HTML5::Browser (soon)

  45. None
  46. Put on your VCS server Generate on every commit

  47. Push to GitHub gh-pages branch

  48. Dist::Zilla plugin coming soon

  49. STEP 2 Dogfood your docs

  50. I’m the only person on my team, I don’t care.

  51. Documentation Driven Development

  52. None
  53. Makes you think before you code

  54. Thinking is good

  55. STEP 3 ???

  56. Use your docs as a marketing tool

  57. Better Docs = Higher perceived quality

  58. None
  59. Abstract Synopsis cpanminus Name

  60. Use GitHub pages

  61. STEP 4 Profit!

  62. Docs are high-level Input, Output, Errors Read docs in rendered

    format When in doubt, cheat. SUMMARY
  63. ~FIN~