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

Docs or it didn't happen! [PyCon UK 2017]

Docs or it didn't happen! [PyCon UK 2017]

**This version of the talk was presented at PyCon UK 2017**

** Video available here: https://youtu.be/muhxjdxhIR0**

If you ever skimmed through a README, tried to follow a quickstart tutorial, attempted to decipher an error message, or typed '--help' in your console, congratulations -- you have encountered documentation!

Long gone are the days of massive books with never-ending stories about your software. Today's users are smarter and less patient, which means that we no longer need to document *all the things*, as long as what we do document is clear, concise, helpful, and accessible. And that's where the real work starts.

Documentation requires some attitude adjustment, since prose doesn't neatly compile into binaries as code does. But Don't Panic(tm)! No matter what your role is in the community, you can apply a few key principles from the technical writing world to make your project more docs-friendly, and therefore more user- and contributor-friendly.

http://2017.pyconuk.org/sessions/talks/docs-or-it-didn-t-happen/

thatdocslady

October 26, 2017
Tweet

More Decks by thatdocslady

Other Decks in Technology

Transcript

  1. DOCS OR IT DIDN’T HAPPEN!
    Mikey Ariel
    @ThatDocsLady @WriteTheDocs
    PyCon UK 2017

    View Slide

  2. Why are we here?
    We are *not* here to argue whether documentation is important (or to argue about anything, really). And please leave
    your flamewars at the door, documentation is communication so let’s remember how to do that.
    This talk will run the full 25 minutes, with no on-stage questions. Personal interaction is recommended (talk to me
    afterwards!), or you can email, Slack, or tweet @ThatDocsLady with your questions any time.
    ◉ We want to have more users and contributors
    ◉ We believe (or want to believe) that docs can help
    ◉ is stopping us from working on docs

    View Slide

  3. Who is That Docs Lady?
    @ThatDocsLady [email protected] @WriteTheDocs

    View Slide

  4. WHAT’S ON THE MENU TODAY?

    View Slide

  5. Content Strategy
    Plan a little, save a lot
    Community Spirit
    We’re all in this together
    DevOps for Docs
    Not just for developers anymore

    View Slide

  6. JOIN THE DOCUMENTARIAN CLUB!

    View Slide


  7. A documentarian is someone who cares
    about documentation and communication in
    the software industry, regardless of job title.
    http://www.writethedocs.org/documentarians/

    View Slide

  8. Documentarians
    Writers
    Developers
    Designers
    DevOps
    Marketing
    Support
    UX

    View Slide

  9. CONTENT STRATEGY
    Asking the right questions in advance can save a lot of time later
    1

    View Slide

  10. NEED-TO-KNOW DOCS
    (and no, you don’t need to know everything)

    View Slide

  11. Need-to-Know Documentation

    View Slide

  12. Need-to-Know Documentation
    Who

    View Slide

  13. Need-to-Know Documentation
    Who What

    View Slide

  14. Need-to-Know Documentation
    Who When
    What

    View Slide

  15. Need-to-Know Documentation
    Who Where
    When
    What

    View Slide

  16. Need-to-Know Documentation
    Who Why
    Where
    When
    What

    View Slide

  17. EXAMPLES
    (because screenshots rock)

    View Slide

  18. GNOME Help
    help.gnome.org
    help.gnome.org

    View Slide

  19. GNOME Help
    help.gnome.org

    View Slide

  20. GNOME Help
    help.gnome.org

    View Slide

  21. GNOME Help
    help.gnome.org

    View Slide

  22. Arch Linux Wiki
    wiki.archlinux.org

    View Slide

  23. Arch Linux Wiki
    wiki.archlinux.org

    View Slide

  24. Minishift README
    github.com/minishift/minishift

    View Slide

  25. Minishift Troubleshooting
    github.com/minishift/minishift/issues/1152

    View Slide

  26. Minishift Troubleshooting
    github.com/minishift/minishift-centos-iso/pull/119

    View Slide

  27. Minishift Troubleshooting
    docs.openshift.org/latest/minishift/troubleshooting/troubleshooting-misc

    View Slide

  28. DEVOPS FOR DOCS
    Geeking out about documentation tooling and workflow
    2

    View Slide

  29. INTEGRATION
    (if you can’t beat them, join them)

    View Slide

  30. UNIFIED TOOLING
    If it ain’t baroque, don’t fix it!

    View Slide

  31. Docs-as-Code
    github.com/minishift/minishift

    View Slide

  32. Modular Source Content
    github.com/minishift/minishift

    View Slide

  33. Issue Tracking
    github.com/minishift/minishift

    View Slide

  34. Issue Tracking
    github.com/minishift/minishift

    View Slide

  35. CONTINUOUS PUBLICATION
    No need to stop the press anymore!

    View Slide

  36. Publication Tools

    View Slide

  37. Continuous Deployment
    readthedocs.org/projects/writethedocs-www/builds

    View Slide

  38. Live-Preview Staging
    github.com/writethedocs/www/pulls/

    View Slide

  39. TESTING AUTOMATION
    More than a just a spell-checker!

    View Slide

  40. Linguistic Validation
    www.hemingwayapp.com

    View Slide

  41. Test Automation Framework
    github.com/emender/emender

    View Slide

  42. COMMUNITY SPIRIT
    Let’s help our contributors help us and help each other
    3

    View Slide


  43. Docs or it didn’t happen!
    - Me, at the beginning of this presentation

    View Slide

  44. Django Project
    Linux Kernel
    OpenStack
    Documentation as a Deliverable

    View Slide

  45. Contribution Guidelines
    nixos.wiki/wiki/Contributing_to_Nix_documentation

    View Slide

  46. Templates
    www.writethedocs.org/guide/writing/beginners-guide-to-docs

    View Slide

  47. The Documentarian
    community is growing!

    View Slide

  48. Dedicated Conferences

    View Slide

  49. Doc Sprints and Hackfests
    Documentation Help Desk during Monday sprints!
    (I have stickers)

    View Slide

  50. @ThatDocsLady [email protected] @WriteTheDocs
    WELCOME TO THE CLUB!

    View Slide