Documentation at ownCloud

Want to know how documentation works at ownCloud? Want to contribute (I'd love if you did) then check out this presentation from ocConf2017.

Transcript

1. Documentation at ownCloud by Matthew Setter ownCloud Documentation Lead
 @settermjd / matthew@matthewsetter.com
2. 2 What Will We Cover? 1. How documentation works at ownCloud 2. How you can contribute
3. 3 How Documentation at ownCloud Works • Implements a developer-like workflow • It’s called Docs as Code
4. 4 What is Docs as Code • It’s not just inline code comments • It’s everything that goes with your software • Yes, everything! • It’s essential
5. 5 Getting Started Guides & How Tos
6. 6 Tutorials
7. 7 API Documentation
8. 8 Even UI Messages
9. 9 What’s That Have To Do With You?
10. 10 Why Docs Are Essential • Help developers start quickly • Help users start quickly • Help users help themselves • Make support more valuable • Help management • Create a more professional perception
11. 11 How Do You Get Started? • Use the same mindset • Use the same tools
12. 12 You Only Need Six Things • Basic English proficiency • Empathy • A willingness to communicate • A text editor (or IDE) • Git • Knowledge of ReStructuredText and Sphinx-Doc
13. 13 Which Editor (or IDE)?
14. 14 Which Git Tool?
15. 15 ReStructuredText 101 • It’s a lot like Markdown and Asciidoc • Simple text format that’s convertible to HTML, PDF, and more • Supports lists, tables, images, links, code, & more
16. 16 Inline Markup
17. 17 Section Structure
18. 18 Links, Cross-References, and Images
19. 19 Tables
20. 20 Setup a Development Environment • Build a Vagrant/VirtualBox VM • or • Use the Vagrant/Ansible provisioner
21. 21 How You Can Contribute 1. If you see a problem, create an issue or a PR 2. If you see something missing create an issue or a PR 3. Contribute to existing issues & PRs 4. I’d love your input 5. Yes — really!
22. 22 Step 1 - Create An Issue
23. 23 Step 2 - Create a Feature Branch
24. 24 Step 3 - Create a PR
25. 25 Step 4 - Review, Approve, & Merge the PR
26. 26 In Conclusion • Documentation is awesome! • It works almost like code • I’d love to get your input
27. 27 Thank You Any Questions? @settermjd matthew@matthewsetter.com
28. 28 Links & Errata • ownCloud docs repository - https://github.com/owncloud/documentation • ownCloud documentation - https://doc.owncloud.com/ • ReStructuredText cheat sheet - https://github.com/ralsina/rst-cheatsheet • Vim for Technical Writers - https://github.com/settermjd/vim-for-technical-writers • Atom reStructuredText plugin - https://atom.io/packages/language-restructuredtext • VS Code reStructuredText plugin - https://github.com/vscode-restructuredtext/vscode-restructuredtext • PhpStorm reStructuredText plugin - https://plugins.jetbrains.com/plugin/7124-restructuredtext-support