Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Documentation at ownCloud

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.

Matthew Setter

September 20, 2017
Tweet

More Decks by Matthew Setter

Other Decks in Technology

Transcript

  1. Documentation at ownCloud
    by Matthew Setter
    ownCloud Documentation Lead

    @settermjd / [email protected]

    View full-size slide

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

    View full-size slide

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

    View full-size 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 full-size slide

  5. 5
    Getting Started Guides & How Tos

    View full-size slide

  6. 7
    API Documentation

    View full-size slide

  7. 8
    Even UI Messages

    View full-size slide

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

    View full-size slide

  9. 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 full-size slide

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

    View full-size slide

  11. 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 full-size slide

  12. 13
    Which Editor (or IDE)?

    View full-size slide

  13. 14
    Which Git Tool?

    View full-size slide

  14. 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 full-size slide

  15. 16
    Inline Markup

    View full-size slide

  16. 17
    Section Structure

    View full-size slide

  17. 18
    Links, Cross-References, and Images

    View full-size slide

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

    View full-size slide

  19. 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 full-size slide

  20. 22
    Step 1 - Create An Issue

    View full-size slide

  21. 23
    Step 2 - Create a Feature Branch

    View full-size slide

  22. 24
    Step 3 - Create a PR

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  25. 27
    Thank You
    Any Questions?
    @settermjd
    [email protected]

    View full-size slide

  26. 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 full-size slide