The formula to awesome docs (phpDay 2017)

Transcript

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.
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.
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.
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
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.
68. Give content space.
69. Use syntax highlighting.
71. Consider adding a search functionality.
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.