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
   

   View Slide

2. 2
   What Will We Cover?
   1. How documentation works at ownCloud
   2. How you can contribute
   

   View Slide

3. 3
   How Documentation at ownCloud Works
   • Implements a developer-like workflow
   • It’s called Docs as Code
   

   View Slide

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
   

   View Slide

5. 5
   Getting Started Guides & How Tos
   

   View Slide

6. 6
   Tutorials
   

   View Slide

7. 7
   API Documentation
   

   View Slide

8. 8
   Even UI Messages
   

   View Slide

9. 9
   What’s That Have To Do With You?
   

   View Slide

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
    

    View Slide

11. 11
    How Do You Get Started?
    • Use the same mindset
    • Use the same tools
    

    View Slide

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
    

    View Slide

13. 13
    Which Editor (or IDE)?
    

    View Slide

14. 14
    Which Git Tool?
    

    View Slide

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
    

    View Slide

16. 16
    Inline Markup
    

    View Slide

17. 17
    Section Structure
    

    View Slide

18. 18
    Links, Cross-References, and Images
    

    View Slide

19. 19
    Tables
    

    View Slide

20. 20
    Setup a Development Environment
    • Build a Vagrant/VirtualBox VM
    • or
    • Use the Vagrant/Ansible provisioner
    

    View Slide

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!
    

    View Slide

22. 22
    Step 1 - Create An Issue
    

    View Slide

23. 23
    Step 2 - Create a Feature Branch
    

    View Slide

24. 24
    Step 3 - Create a PR
    

    View Slide

25. 25
    Step 4 - Review, Approve, & Merge the PR
    

    View Slide

26. 26
    In Conclusion
    • Documentation is awesome!
    • It works almost like code
    • I’d love to get your input
    

    View Slide

27. 27
    Thank You
    Any Questions?
    @settermjd
    matthew@matthewsetter.com
    

    View Slide

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
    

    View Slide