$30 off During Our Annual Pro Sale. View Details »

Docs or it didn't happen! [Prague PostgreSQL Meetup, November 2018]

thatdocslady
November 26, 2018

Docs or it didn't happen! [Prague PostgreSQL Meetup, November 2018]

**This version of the talk was presented at the PostgreSQL Prague Meetup**

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.

thatdocslady

November 26, 2018
Tweet

More Decks by thatdocslady

Other Decks in Technology

Transcript

  1. DOCS OR IT DIDN’T HAPPEN!
    Mikey Ariel
    @ThatDocsLady @WriteTheDocs
    PostgreSQL Prague Meetup, November 2018

    View Slide

  2. Why are we here?
    ◉ 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
    Why

    View Slide

  15. Need-to-Know Documentation
    Why Who

    View Slide

  16. Need-to-Know Documentation
    Why What
    Who

    View Slide

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

    View Slide

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

    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. Docs-as-Code
    github.com/minishift/minishift

    View Slide

  33. Hierarchical Source Content
    github.com/minishift/minishift

    View Slide

  34. Issue Tracking
    github.com/minishift/minishift

    View Slide

  35. Issue Tracking
    github.com/minishift/minishift

    View Slide

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

    View Slide

  37. Publication Tools

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  41. Linguistic Validation
    www.hemingwayapp.com

    View Slide

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

    View Slide

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

    View Slide


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

    View Slide

  45. Django Project
    Linux Kernel
    OpenStack
    Documentation as a Deliverable

    View Slide

  46. Contribution Workflow
    nixos.wiki/wiki/Contributing_to_Nix_documentation

    View Slide

  47. Contribution Process
    redhat-documentation.github.io/community-collaboration-guide

    View Slide

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

    View Slide

  49. Templates
    github.com/redhat-documentation/modular-docs

    View Slide

  50. The Documentarian
    club is growing!

    View Slide

  51. Documentation Conferences

    View Slide

  52. Doc-to-Dev Outreach

    View Slide

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

    View Slide