Save 37% off PRO during our Black Friday Sale! »

Docs or it didn't happen! [Prague PostgreSQL Meetup, November 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.



November 26, 2018


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

    Prague Meetup, November 2018
  2. Why are we here? ◉ 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 @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.”
  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 Why

  15. Need-to-Know Documentation Why Who

  16. Need-to-Know Documentation Why What Who

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

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

  19. EXAMPLES (because screenshots are awesome)

  20. GNOME Help

  21. GNOME Help

  22. GNOME Help

  23. GNOME Help

  24. Arch Linux Wiki

  25. Arch Linux Wiki

  26. Minishift README

  27. Minishift Troubleshooting

  28. Minishift Troubleshooting

  29. Minishift Troubleshooting

  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. Docs-as-Code

  33. Hierarchical Source Content

  34. Issue Tracking

  35. Issue Tracking

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

  37. Publication Tools

  38. Continuous Deployment

  39. Live-Preview Staging<YOUR-PR-HERE>

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

  41. Linguistic Validation

  42. Test Automation Framework

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

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

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

  46. Contribution Workflow

  47. Contribution Process

  48. Templates

  49. Templates

  50. The Documentarian club is growing!

  51. Documentation Conferences

  52. Doc-to-Dev Outreach

  53. @ThatDocsLady @WriteTheDocs WELCOME TO THE CLUB!