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

Documentation Journey

November 08, 2013

Documentation Journey

A talk about Documentation I gave a PDXNode in November 2013


November 08, 2013

More Decks by ericholscher

Other Decks in Technology


  1. What This Talk Is • High level overview of how

    to think about documentation • Why documentation matters • Overview of my thoughts on doing docs well • Discussion around Node community documentation
  2. What this talk isn’t • Telling you how to write

    docs • User/Product documentation
  3. Who am I • Maintainer of Read the Docs •

    Co-Organizer of Write the Docs
  4. outreach • We want more people to code • How

    do I become a programmer? • Having good documentation allows people to learn how to program
  5. Internationalization • Documentation is much more accessible for non-native speakers

    • Text is most easily translated into other languages
  6. Other Audiences • Each tool is unique • People want

    to use your code, so make it easy for them, whoever they are.
  7. Tutorials • Be quick • Be easy (but not too

    easy) • Give a “feel” for your project
  8. Tutorials • Great for people who are new to your

    project • Should aim to delight or scare
  9. Topical Guides • Great for people who don’t know your

    project space well • Give you the “why” • The “meat” of your docs
  10. Official • Good documentation comes from the project • Must

    be constantly updated with code changes • Put process in place
  11. README’s • Great for small projects • Provide a very

    specific thing • Basically a “getting started” doc
  12. Blog Posts • Quickly goes out of date • Stack

    Overflow solves this problem better • Good for Topical Guides
  13. State of the Art • Folder Full of Markdown •

    Served on GitHub • “Website”
  14. Standard Tooling • Need a common format • Where you

    go a er a folder full of markdown • Not “build a custom website”
  15. Easy and Obvious • New users need an easy way

    to get started • There needs to be an obvious path towards a good solution
  16. Community • Docs are a community problem • You need

    to expect them and complain if they don’t exist
  17. Young • You can help shape what the world looks

    like • Derived projects will follow your lead
  18. Conclusion • Good documentation is hard work • Documentation acts

    as outreach • Work to improve tools, to make writing documentation easier