The formula to awesome docs (phpDay 2017)

The formula to awesome docs (phpDay 2017)

6074dbe5dfa361c9888a705f40a49af4?s=128

Jonathan Reinink

May 13, 2017
Tweet

Transcript

  1. None
  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.
  3. None
  4. I love documentation.

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

  6. I enjoy the teaching aspect of documentation.

  7. I enjoy the learning aspect to documentation.

  8. Good docs are vital to the success of libraries, frameworks,

    languages and technical services.
  9. Developers will give something the time of day, if it's

    clear you have.
  10. Myths of documentation.

  11. Documentation myth #1: "Read the code" is an acceptable answer

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

  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.”
  14. Documentation myth #3: "All you need a README file.”

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

  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)
  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)
  18. The purpose of documentation.

  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
  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
  21. Must read article: Teach, Don't Tell stevelosh.com/blog/2013/09/teach-dont-tell/ By Steve Losh

  22. The Anatomy of Good Documentation 1. The pitch 2. The

    example 3. The guides 4. The reference
  23. 1. The pitch

  24. The elevator speech.

  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?
  26. For bonus points, you can also mention why someone might

    want to not use your project.
  27. “This package is a port from the Ruby X package.”

    Not acceptable:
  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.
  29. 2. The minimum viable example

  30. The minimum viable example lets your prospective user get some

    paint on the canvas.
  31. None
  32. None
  33. 3. The guides

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

    to be covered.
  35. Don’t be afraid to write.

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

    section of the guides.
  37. Be liberal with your use of sub titles.

  38. Include lots of examples.

  39. 4. The reference

  40. Keep a change log.

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

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

  43. None
  44. {% for release in site.github.releases %} ## [{{ release.name }}]({{

    release.html_url }}) - {{ release.published_at | date: "%Y-%m-%d" }} {{ release.body | markdownify }} {% endfor %}
  45. Make sure your API docs are actually useful.

  46. Welcome contributions.

  47. Putting it all together.

  48. The ideal layout.

  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
  50. None
  51. None
  52. None
  53. None
  54. None
  55. None
  56. None
  57. None
  58. None
  59. None
  60. None
  61. None
  62. None
  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
  64. The design of your docs matters.

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

    Pro Droid Sans
  66. Use a nice colour scheme.

  67. None
  68. Give content space.

  69. Use syntax highlighting.

  70. None
  71. Consider adding a search functionality.

  72. None
  73. None
  74. Include a link where corrections can be submitted.

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

    interested in.
  76. Don’t get hung up on the tooling.

  77. Go forth and make awesome docs!

  78. Thanks! Follow me on Twitter at @reinink. Please rate this

    talk at joind.in/talk/9a9dc.