The formula to awesome docs (phpDay 2017)

Transcript

1. View Slide

2. Jonathan Reinink
   I live in Canada.
   I have been writing PHP for 18 years.
   I spent a decade at marketing agency.
   I am now a contract developer.
   

   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. "Auto-generated API
    docs are good enough.”
    Documentation myth #2:
    

    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
    …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 should be easy.”
    Documentation myth #4:
    

    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 more fun?
    

    View Slide

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

    View Slide

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

    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. Don’t get hung up
    on the tooling.
    

    View Slide

77. Go forth and make
    awesome docs!
    

    View Slide

78. Thanks!
    Follow me on Twitter at @reinink.
    Please rate this talk at joind.in/talk/9a9dc.
    

    View Slide