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

Docs or it didn't happen! [FOSS North 2019]

Docs or it didn't happen! [FOSS North 2019]

**This version of the talk was presented at FOSS North 2019**

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, 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://foss-north.se/2019/speakers-and-talks.html#mariel

thatdocslady

April 08, 2019
Tweet

More Decks by thatdocslady

Other Decks in Technology

Transcript

  1. DOCS OR IT DIDN’T HAPPEN!
    Mikey Ariel
    @ThatDocsLady @WriteTheDocs
    FOSS North, April 2019

    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 45 minutes, with no on-stage questions. Personal interaction is recommended (find me at the Red
    Hat booth!), 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. Why
    Need-to-Know Documentation

    View Slide

  15. Why Who
    Need-to-Know Documentation

    View Slide

  16. Why What
    Who
    Need-to-Know Documentation

    View Slide

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

    View Slide

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

    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. Code Blocks Validation
    github.com/endocode/shelldoc

    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 Guides
    nixos.wiki/wiki/Contributing_to_Nix_documentation

    View Slide

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

    View Slide

  49. Modular Docs Project
    github.com/redhat-documentation/modular-docs

    View Slide

  50. Modular Docs Project
    redhat-documentation.github.io/modular-docs

    View Slide

  51. Modular Docs Project
    github.com/redhat-documentation/modular-docs/tree/master/modular-docs-manual/files

    View Slide

  52. Modular Docs Project
    [...]/modular-docs-manual/filesTEMPLATE_PROCEDURE_doing-one-procedure.adoc

    View Slide

  53. Community-to-Enterprise
    redhat-documentation.github.io/community-collaboration-guide

    View Slide

  54. The Documentarian
    community is growing!

    View Slide

  55. Write the Docs

    View Slide

  56. Season of Docs
    developers.google.com/season-of-docs

    View Slide

  57. Doc-to-Dev Outreach
    Find me for a chat at the Red Hat Booth!
    (I have stickers)

    View Slide

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

    View Slide