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!

Transcript

1. View Slide

2. 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 Slide

3. View Slide

4. I love
   documentation.
   

   View Slide

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

   View Slide

6. I enjoy the
   teaching aspect of
   documentation.
   

   View Slide

7. I enjoy the
   learning aspect to
   documentation.
   

   View Slide

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

   View Slide

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

   View Slide

10. Myths of
    documentation.
    

    View Slide

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

    View Slide

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

    View Slide

13. — 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 Slide

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

    View Slide

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

    View Slide

16. “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 Slide

17. “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 Slide

18. The purpose of
    documentation.
    

    View Slide

19. “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 Slide

20. “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 Slide

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

    View Slide

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

    View Slide

23. 1. The pitch
    

    View Slide

24. The elevator speech.
    

    View Slide

25. 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 Slide

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

    View Slide

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

    View Slide

28. 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 Slide

29. 2. The minimum
    viable example
    

    View Slide

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

    View Slide

31. View Slide

32. View Slide

33. 3. The guides
    

    View Slide

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

    View Slide

35. Don’t be afraid
    to write.
    

    View Slide

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

    View Slide

37. Be liberal with your
    use of sub titles.
    

    View Slide

38. Include lots of
    examples.
    

    View Slide

39. 4. The reference
    

    View Slide

40. Keep a change log.
    

    View Slide

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

    View Slide

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

    View Slide

43. View Slide

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

    View Slide

45. Make sure your
    API docs are
    actually useful.
    

    View Slide

46. Welcome
    contributions.
    

    View Slide

47. Putting it all
    together.
    

    View Slide

48. The ideal layout.
    

    View Slide

49. 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 Slide

50. View Slide

51. View Slide

52. View Slide

53. View Slide

54. View Slide

55. View Slide

56. View Slide

57. View Slide

58. View Slide

59. View Slide

60. View Slide

61. View Slide

62. View Slide

63. 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 Slide

64. The design of your
    docs matters.
    

    View Slide

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

    View Slide

66. Use a nice
    colour scheme.
    

    View Slide

67. View Slide

68. Give content space.
    

    View Slide

69. Use syntax
    highlighting.
    

    View Slide

70. View Slide

71. Consider adding a
    search functionality.
    

    View Slide

72. View Slide

73. View Slide

74. Include a link
    where corrections
    can be submitted.
    

    View Slide

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

    View Slide

76. Go forth and make
    awesome docs.
    

    View Slide

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

    View Slide