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

Transcript

1. DOCS OR IT DIDN’T HAPPEN! Mikey Ariel @ThatDocsLady @WriteTheDocs FOSS North, April 2019
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 ◉ <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
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
8. JOIN THE DOCUMENTARIAN CLUB!
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. Why Need-to-Know Documentation
15. Why Who Need-to-Know Documentation
16. Why What Who Need-to-Know Documentation
17. Why When What Who Need-to-Know Documentation
18. Why Where When What Who Need-to-Know Documentation
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. Docs-as-Code github.com/minishift/minishift
33. Hierarchical Source Content github.com/minishift/minishift
34. Issue Tracking github.com/minishift/minishift
35. Issue Tracking github.com/minishift/minishift
36. CONTINUOUS PUBLICATION No need to stop the press anymore!
37. Publication Tools
38. Continuous Deployment readthedocs.org/projects/writethedocs-www/builds
39. Live-Preview Staging github.com/writethedocs/www/pulls/<YOUR-PR-HERE>
40. TESTING AUTOMATION More than a just a spell-checker!
41. Code Blocks Validation github.com/endocode/shelldoc
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 Guides nixos.wiki/wiki/Contributing_to_Nix_documentation
48. Templates www.writethedocs.org/guide/writing/beginners-guide-to-docs
49. Modular Docs Project github.com/redhat-documentation/modular-docs
50. Modular Docs Project redhat-documentation.github.io/modular-docs
51. Modular Docs Project github.com/redhat-documentation/modular-docs/tree/master/modular-docs-manual/files
52. Modular Docs Project [...]/modular-docs-manual/filesTEMPLATE_PROCEDURE_doing-one-procedure.adoc
53. Community-to-Enterprise redhat-documentation.github.io/community-collaboration-guide
54. The Documentarian community is growing!
55. Write the Docs
56. Season of Docs developers.google.com/season-of-docs
57. Doc-to-Dev Outreach Find me for a chat at the Red Hat Booth! (I have stickers)
58. @ThatDocsLady docs@docsideofthemoon.com @WriteTheDocs WELCOME TO THE CLUB!