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!

6074dbe5dfa361c9888a705f40a49af4?s=128

Jonathan Reinink

April 09, 2016
Tweet

Transcript

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

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

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

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

    want to not use your project.
  27. Not acceptable: “This package is a port from the Ruby

    X package.”
  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. Go forth and make awesome docs.

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

    talk at joind.in/talk/f2272.