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

Documentation for Fun and Profit

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
Tweet

Other Decks in Programming

Transcript

  1. Documentation
    for fun and profit

    View Slide

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

    View Slide

  3. You need good
    documentation

    View Slide

  4. But hate writing it…

    View Slide

  5. CHEAT!

    View Slide

  6. What is
    documentation?

    View Slide

  7. Code Comments?

    View Slide

  8. PyDoc
    RDoc
    TomDoc
    Docco
    Rocco
    Pycco
    PHPDoc
    JavaDoc
    YARD
    Doxygen
    JSDoc
    Epydoc
    CSSDoc
    KSS
    StyleDoc
    Other Languages

    View Slide

  9. Not in Perl

    View Slide

  10. Documentation
    =
    High Level
    =head2 validate_email
    This method determines whether an
    email address is valid or not

    View Slide

  11. Comments
    =
    Low Level
    # Use a naive regex to check emails
    # because I hate maintenance devs
    sub validate_email {

    View Slide

  12. View Slide

  13. POD
    Plain Old Documentation

    View Slide

  14. Markup language,
    like HTML

    View Slide

  15. POD Sucks

    View Slide

  16. POD Sucks
    (On Purpose)

    View Slide

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

    View Slide

  18. POD is everywhere

    View Slide

  19. STEP 1
    Know your audience

    View Slide

  20. What is good
    documentation

    View Slide

  21. Good
    Docs
    Must Be
    Clear
    Complete
    Concise

    View Slide

  22. Good
    Docs
    Answer
    Input
    Output
    Errors

    View Slide

  23. Missing one thing…

    View Slide

  24. Keep the docs
    up to date!

    View Slide

  25. Laziness
    Impatience
    Hubris

    View Slide

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

    View Slide

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

    View Slide

  28. “The code is
    self-explanatory”
    everyone

    View Slide

  29. MORE CODE!

    View Slide

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

    View Slide

  31. MORE CODE!
    LESS CODE!

    View Slide

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

    View Slide

  33. CHEAT!

    View Slide

  34. Documentation
    needs a killer feature

    View Slide

  35. View Slide

  36. “I thought it was
    pointless at first,
    but now I can’t live
    without it”
    colleague

    View Slide

  37. 82.4%* of people
    read POD unparsed
    * made up statistic

    View Slide

  38. Like coding
    without ‘strict’ on

    View Slide

  39. Readable docs
    =
    Useful docs

    View Slide

  40. We’re engineers,
    not designers…

    View Slide

  41. View Slide

  42. CHEAT!

    View Slide

  43. POD::HTML5::Browser

    View Slide

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

    View Slide

  45. View Slide

  46. Put on your VCS server
    Generate on every commit

    View Slide

  47. Push to GitHub
    gh-pages branch

    View Slide

  48. Dist::Zilla plugin
    coming soon

    View Slide

  49. STEP 2
    Dogfood your docs

    View Slide

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

    View Slide

  51. Documentation
    Driven
    Development

    View Slide

  52. View Slide

  53. Makes you think
    before you code

    View Slide

  54. Thinking is good

    View Slide

  55. STEP 3
    ???

    View Slide

  56. Use your docs as a
    marketing tool

    View Slide

  57. Better Docs
    =
    Higher perceived quality

    View Slide

  58. View Slide

  59. Abstract
    Synopsis
    cpanminus
    Name

    View Slide

  60. Use GitHub pages

    View Slide

  61. STEP 4
    Profit!

    View Slide

  62. Docs are high-level
    Input, Output, Errors
    Read docs in rendered format
    When in doubt, cheat.
    SUMMARY

    View Slide

  63. ~FIN~

    View Slide