Docs or it didn't happen! [PyCon UK 2017]

**This version of the talk was presented at PyCon UK 2017**

** Video available here: https://youtu.be/muhxjdxhIR0**

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.

http://2017.pyconuk.org/sessions/talks/docs-or-it-didn-t-happen/

Transcript

1. DOCS OR IT DIDN’T HAPPEN! Mikey Ariel @ThatDocsLady @WriteTheDocs PyCon UK 2017
2. Why are we here? We are *not* here to argue whether documentation is important (or to argue about anything, really). And please leave your flamewars at the door, documentation is communication so let’s remember how to do that. This talk will run the full 25 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 docs@docsideofthemoon.com @WriteTheDocs
4. WHAT’S ON THE MENU TODAY?
5. Content Strategy Plan a little, save a lot Community Spirit We’re all in this together DevOps for Docs Not just for developers anymore
6. JOIN THE DOCUMENTARIAN CLUB!
7. “ A documentarian is someone who cares about documentation and communication in the software industry, regardless of job title. http://www.writethedocs.org/documentarians/
8. Documentarians Writers Developers Designers DevOps Marketing Support UX
9. CONTENT STRATEGY Asking the right questions in advance can save a lot of time later 1
10. NEED-TO-KNOW DOCS (and no, you don’t need to know everything)
11. Need-to-Know Documentation
12. Need-to-Know Documentation Who
13. Need-to-Know Documentation Who What
14. Need-to-Know Documentation Who When What
15. Need-to-Know Documentation Who Where When What
16. Need-to-Know Documentation Who Why Where When What
17. EXAMPLES (because screenshots rock)
18. GNOME Help help.gnome.org help.gnome.org
19. GNOME Help help.gnome.org
20. GNOME Help help.gnome.org
21. GNOME Help help.gnome.org
22. Arch Linux Wiki wiki.archlinux.org
23. Arch Linux Wiki wiki.archlinux.org
24. Minishift README github.com/minishift/minishift
25. Minishift Troubleshooting github.com/minishift/minishift/issues/1152
26. Minishift Troubleshooting github.com/minishift/minishift-centos-iso/pull/119
27. Minishift Troubleshooting docs.openshift.org/latest/minishift/troubleshooting/troubleshooting-misc
28. DEVOPS FOR DOCS Geeking out about documentation tooling and workflow 2
29. INTEGRATION (if you can’t beat them, join them)
30. UNIFIED TOOLING If it ain’t baroque, don’t fix it!
31. Docs-as-Code github.com/minishift/minishift
32. Modular Source Content github.com/minishift/minishift
33. Issue Tracking github.com/minishift/minishift
34. Issue Tracking github.com/minishift/minishift
35. CONTINUOUS PUBLICATION No need to stop the press anymore!
36. Publication Tools
37. Continuous Deployment readthedocs.org/projects/writethedocs-www/builds
38. Live-Preview Staging github.com/writethedocs/www/pulls/<YOUR-PR-HERE>
39. TESTING AUTOMATION More than a just a spell-checker!
40. Linguistic Validation www.hemingwayapp.com
41. Test Automation Framework github.com/emender/emender
42. COMMUNITY SPIRIT Let’s help our contributors help us and help each other 3
43. “ Docs or it didn’t happen! - Me, at the beginning of this presentation
44. Django Project Linux Kernel OpenStack Documentation as a Deliverable
45. Contribution Guidelines nixos.wiki/wiki/Contributing_to_Nix_documentation
46. Templates www.writethedocs.org/guide/writing/beginners-guide-to-docs
47. The Documentarian community is growing!
48. Dedicated Conferences
49. Doc Sprints and Hackfests Documentation Help Desk during Monday sprints! (I have stickers)
50. @ThatDocsLady docs@docsideofthemoon.com @WriteTheDocs WELCOME TO THE CLUB!