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

Docs or it didn't happen! [PyCon SK 2018]

Docs or it didn't happen! [PyCon SK 2018]

**This version of the talk was presented at PyCon SK 2018**

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.

https://2018.pycon.sk/en/speakers/Ariel.html

thatdocslady

March 09, 2018
Tweet

More Decks by thatdocslady

Other Decks in Technology

Transcript

  1. DOCS OR IT DIDN’T HAPPEN!
    Mikey Ariel
    @ThatDocsLady @WriteTheDocs
    PyCon SK, March 2018

    View Slide

  2. Why are we here?
    We are *not* here to argue whether documentation is important (or to argue about anything, really).
    Please leave your flamewars at the door, documentation is communication so let’s remember how to do that.
    This talk will run the full 30 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

    View Slide

  6. Content Strategy
    Plan a little, save a lot
    DevOps for Docs
    Not just for developers anymore

    View Slide

  7. 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

  8. JOIN THE DOCUMENTARIAN CLUB!

    View Slide


  9. “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

  10. Community
    Writers
    DevOps Testers
    Designers
    Marketing
    Developers
    Support
    Documentarians

    View Slide

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

    View Slide

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

    View Slide

  13. Need-to-Know Documentation

    View Slide

  14. Need-to-Know Documentation
    Who

    View Slide

  15. Need-to-Know Documentation
    Who What

    View Slide

  16. Need-to-Know Documentation
    Who When
    What

    View Slide

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

    View Slide

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

    View Slide

  19. EXAMPLES
    (because screenshots are awesome)

    View Slide

  20. GNOME Help
    help.gnome.org
    help.gnome.org

    View Slide

  21. GNOME Help
    help.gnome.org

    View Slide

  22. GNOME Help
    help.gnome.org

    View Slide

  23. GNOME Help
    help.gnome.org

    View Slide

  24. Arch Linux Wiki
    wiki.archlinux.org

    View Slide

  25. Arch Linux Wiki
    wiki.archlinux.org

    View Slide

  26. Minishift README
    github.com/minishift/minishift

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  30. DEVOPS FOR DOCS
    Let’s geek out about processes, tools, and workflows, oh my!
    2

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  35. Issue Tracking
    github.com/minishift/minishift

    View Slide

  36. Issue Tracking
    github.com/minishift/minishift

    View Slide

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

    View Slide

  38. Publication Tools

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  42. Linguistic Validation
    www.hemingwayapp.com

    View Slide

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

    View Slide

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

    View Slide


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

    View Slide

  46. Django Project
    Linux Kernel
    OpenStack
    Documentation as a Deliverable

    View Slide

  47. Contribution Guidelines
    nixos.wiki/wiki/Contributing_to_Nix_documentation

    View Slide

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

    View Slide

  49. The Documentarian
    community is growing!

    View Slide

  50. Dedicated Conferences

    View Slide

  51. Doc Sprints and Hackfests
    Documentation Help Desk on Sunday!
    (I have stickers)

    View Slide

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

    View Slide