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

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.
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.
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. Go forth and make awesome docs.
77. Thanks! Follow me on Twitter at @reinink. Please rate this talk at joind.in/talk/f2272.