Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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!

Jonathan Reinink

April 09, 2016
Tweet

More Decks by Jonathan Reinink

Other Decks in Technology

Transcript

  1. 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.
  2. — 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.”
  3. “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)
  4. “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)
  5. “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
  6. “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
  7. The Anatomy of Good Documentation 1. The pitch 2. The

    example 3. The guides 4. The reference
  8. 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?
  9. 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.
  10. {% for release in site.github.releases %} ## [{{ release.name }}]({{

    release.html_url }}) - {{ release.published_at | date: "%Y-%m-%d" }} {{ release.body | markdownify }} {% endfor %}
  11. 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
  12. 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