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.



March 09, 2018

More Decks by thatdocslady

Other Decks in Technology


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

    SK, March 2018
  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 ◉ <something> is stopping us from working on docs
  3. Who is That Docs Lady? @ThatDocsLady [email protected] @WriteTheDocs


  5. Content Strategy Plan a little, save a lot

  6. Content Strategy Plan a little, save a lot DevOps for

    Docs Not just for developers anymore
  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

  9. “ “A documentarian is someone who cares about documentation and

    communication in the software industry, regardless of job title.” http://www.writethedocs.org/documentarians/
  10. Community Writers DevOps Testers Designers Marketing Developers Support Documentarians

  11. CONTENT STRATEGY Asking the right questions in advance can save

    a lot of time later 1
  12. NEED-TO-KNOW DOCS (and no, you don’t need to know everything)

  13. Need-to-Know Documentation

  14. Need-to-Know Documentation Who

  15. Need-to-Know Documentation Who What

  16. Need-to-Know Documentation Who When What

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

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

  19. EXAMPLES (because screenshots are awesome)

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

  21. GNOME Help help.gnome.org

  22. GNOME Help help.gnome.org

  23. GNOME Help help.gnome.org

  24. Arch Linux Wiki wiki.archlinux.org

  25. Arch Linux Wiki wiki.archlinux.org

  26. Minishift README github.com/minishift/minishift

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

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

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

  30. DEVOPS FOR DOCS Let’s geek out about processes, tools, and

    workflows, oh my! 2
  31. INTEGRATION (if you can’t beat them, join them)

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

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

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

  35. Issue Tracking github.com/minishift/minishift

  36. Issue Tracking github.com/minishift/minishift

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

  38. Publication Tools

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

  40. Live-Preview Staging github.com/writethedocs/www/pulls/<YOUR-PR-HERE>

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

  42. Linguistic Validation www.hemingwayapp.com

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

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

    each other 3
  45. “ Docs or it didn’t happen! - Me, at the

    beginning of this presentation
  46. Django Project Linux Kernel OpenStack Documentation as a Deliverable

  47. Contribution Guidelines nixos.wiki/wiki/Contributing_to_Nix_documentation

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

  49. The Documentarian community is growing!

  50. Dedicated Conferences

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

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