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

The formula to awesome docs (Lone Star PHP 2016)

The formula to awesome docs (Lone Star PHP 2016)

We all like to complain about bad documentation, but how many of us actually know how to create good docs? Quality docs are vital to the success of any project, and yet so often they're an afterthought. In this talk I'll show you very specifically how to create rock solid docs that your users will love. I'll cover the ideal layout, branding principles, design techniques, syntax highlighting, content organization and more!

Jonathan Reinink

April 09, 2016
Tweet

More Decks by Jonathan Reinink

Other Decks in Technology

Transcript

  1. Jonathan Reinink
    Software developer from Canada.
    Been writing PHP for over 15 years.
    Marketing agency for over a decade.
    Started contract development this year.
    I <3 open source.

    View full-size slide

  2. I love
    documentation.

    View full-size slide

  3. I enjoy the branding
    and marketing aspect
    of documentation.

    View full-size slide

  4. I enjoy the
    teaching aspect of
    documentation.

    View full-size slide

  5. I enjoy the
    learning aspect to
    documentation.

    View full-size slide

  6. Good docs are vital to
    the success of libraries,
    frameworks, languages
    and technical services.

    View full-size slide

  7. Developers will give
    something the time of
    day, if it's clear you have.

    View full-size slide

  8. Myths of
    documentation.

    View full-size slide

  9. Documentation myth #1:
    "Read the code" is an
    acceptable answer to
    "Where are the docs?"

    View full-size slide

  10. Documentation myth #2:
    "Auto-generated API
    docs are good enough.”

    View full-size slide

  11. — Jacob Kaplan-Moss

    (Core contributor to Django)
    “Auto-generated documentation is almost
    worthless. At best it’s a slightly improved version
    of simply browsing through the source, but most
    of the time it’s easier just to read the source than
    to navigate the bullshit that these autodoc tools
    produce…there’s no substitute for documentation
    written, organized, and edited by hand.”

    View full-size slide

  12. Documentation myth #3:
    "All you need a
    README file.”

    View full-size slide

  13. Documentation myth #4:
    "Documentation
    should be easy.”

    View full-size slide

  14. “Tests are hard so we
    practice to get better.
    Docs are hard… so we don't
    write any and complain.”
    Steve Klabnik, Senior Technical Writer
    (Maintainer of the official Rust documentation)

    View full-size slide

  15. “The difference between excellent
    docs and adequate docs is massive,
    and takes a lot of work. But going
    from bad docs to adequate docs is
    totally achievable.”
    Steve Klabnik, Senior Technical Writer
    (Maintainer of the official Rust documentation)

    View full-size slide

  16. The purpose of
    documentation.

    View full-size slide

  17. “The purpose of technical
    documentation is to take someone
    who has never seen your project,
    teach them to be an expert user of
    it, and support them once they
    become an expert.”
    — Steve Losh

    View full-size slide

  18. “The purpose of technical
    documentation is to take someone
    who has never seen your project,
    teach them to be an expert user of
    it, and support them once they
    become an expert.”
    — Steve Losh

    View full-size slide

  19. Must read article:
    Teach, Don't Tell
    stevelosh.com/blog/2013/09/teach-dont-tell/
    By Steve Losh

    View full-size slide

  20. The Anatomy of
    Good Documentation
    1. The pitch
    2. The example
    3. The guides
    4. The reference

    View full-size slide

  21. 1. The pitch

    View full-size slide

  22. The elevator speech.

    View full-size slide

  23. Will it save me time?
    Will it take more time, but
    be more stable in exchange?
    Does it offer some special
    features I can’t live without?
    Is it just plain fun?

    View full-size slide

  24. For bonus points, you
    can also mention why
    someone might want to
    not use your project.

    View full-size slide

  25. Not acceptable:
    “This package is a port
    from the Ruby X package.”

    View full-size slide

  26. What license the project uses.
    Where the bug tracker is.
    Who the author is.
    Where the source code is.
    How many times it’s been downloaded.

    View full-size slide

  27. 2. The minimum
    viable example

    View full-size slide

  28. The minimum viable
    example lets your
    prospective user get
    some paint on the canvas.

    View full-size slide

  29. 3. The guides

    View full-size slide

  30. Have a guide for every
    topic that you feel
    needs to be covered.

    View full-size slide

  31. Don’t be afraid
    to write.

    View full-size slide

  32. You should have a
    table of contents
    that lists each
    section of the guides.

    View full-size slide

  33. Be liberal with your
    use of sub titles.

    View full-size slide

  34. Include lots of
    examples.

    View full-size slide

  35. 4. The reference

    View full-size slide

  36. Keep a change log.

    View full-size slide

  37. Show notable changes
    that have been made
    between releases.

    View full-size slide

  38. Consider following the
    Keep a CHANGELOG format,
    see keepachangelog.com.

    View full-size slide

  39. {% for release in site.github.releases %}
    ## [{{ release.name }}]({{ release.html_url }})
    - {{ release.published_at | date: "%Y-%m-%d" }}
    {{ release.body | markdownify }}
    {% endfor %}

    View full-size slide

  40. Make sure your
    API docs are
    actually useful.

    View full-size slide

  41. Welcome
    contributions.

    View full-size slide

  42. Putting it all
    together.

    View full-size slide

  43. The ideal layout.

    View full-size slide

  44. Project Name your tagline goes here
    Topic
    Page name
    Page name
    Page name
    Page name
    Topic
    Page name
    Page name
    Page name
    Page name
    Topic
    Page name
    Page name
    Page name
    Page name
    Page name
    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
    eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
    ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
    aliquip ex ea commodo consequat. Duis aute irure dolor in
    reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
    pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa
    qui officia deserunt mollit anim id est laborum.
    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
    eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
    ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
    Sub title
    Search…
    1.0.0

    View full-size slide

  45. Project Name your tagline goes here
    Topic
    Page name
    Page name
    Page name
    Page name
    Topic
    Page name
    Page name
    Page name
    Page name
    Topic
    Page name
    Page name
    Page name
    Page name
    Page name
    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
    eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
    ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
    aliquip ex ea commodo consequat. Duis aute irure dolor in
    reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
    pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa
    qui officia deserunt mollit anim id est laborum.
    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
    eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
    ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
    Sub title
    Search…
    1.0.0

    View full-size slide

  46. The design of your
    docs matters.

    View full-size slide

  47. Choose a better font.
    Museo Sans
    Open Sans
    Source Sans Pro
    Droid Sans

    View full-size slide

  48. Use a nice
    colour scheme.

    View full-size slide

  49. Give content space.

    View full-size slide

  50. Use syntax
    highlighting.

    View full-size slide

  51. Consider adding a
    search functionality.

    View full-size slide

  52. Include a link
    where corrections
    can be submitted.

    View full-size slide

  53. Install Google
    Analytics to see what
    content people are
    most interested in.

    View full-size slide

  54. Go forth and make
    awesome docs.

    View full-size slide

  55. Thanks!
    Follow me on Twitter at @reinink.
    Please rate this talk at joind.in/talk/f2272.

    View full-size slide