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

Working with Documentation, The OpenStack Way

Working with Documentation, The OpenStack Way

Back in the old days, OpenStack's documentation was managed by a central team and written in the unspeakable horror that is DocBook. Things have changed a lot since then, with documentation now spread out across multiple projects and Sphinx the documentation tool du jour. This presents a lot of opportunities for people, be they long-term contributors or novices, to make a real impact to OpenStack's documentation. In this talk, we detail how one can get started contributing in this area, be it through writing your own guides, using Sphinx to automatically generate docs or simply fixing a typo. Viva la documentation!

**What can I expect to learn?**

Since the fall of the documentation team, documentation in projects has often lagged the code, often quite significantly. There's no reason this should be the case. Contributing documentation can be a very easy process for someone already versed in the ways of Git and Gerrit, and this talk should serve to highlight this fact along with the power of Sphinx as a documentation tool.

https://www.openstack.org/summit/denver-2019/summit-schedule/events/23292/working-with-documentation-the-openstack-way

Stephen Finucane

April 30, 2019
Tweet

More Decks by Stephen Finucane

Other Decks in Technology

Transcript

  1. Working with Documentation,
    The OpenStack Way™
    How OpenStack Does Documentation
    Alex Settle
    Technical Writer, SUSE
    @dewsday
    Stephen Finucane
    Software Engineer, Red Hat
    @stephenfin
    Photo by Susan Yin on Unsplash

    View Slide

  2. Past (where we’ve come from)
    Present (where we’re at)
    Future (where we’re going)
    AGENDA

    View Slide

  3. Software Engineer at .
    Working on since ~2015
    I go where the people need me no one else
    wants to go
    Tech Writer at .
    Working on since ~2014
    My whole career has mostly been a happy
    accident.
    WHO DIS?

    View Slide

  4. Past (where we’ve come from)
    Present (where we’re at)
    Future (where we’re going)
    PAST

    View Slide

  5. Past (where we’ve come from)
    Present (where we’re at)
    Future (where we’re going)
    PAST

    View Slide

  6. PAST
    xmlns="http://docbook.org/ns/docbook"
    xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns:xlink="http://www.w3.org/1999/xlink"
    version="5.0">
    Install nova-volume on the cloud controller
    While nova-volume does not directly use the network, you must
    have networking set up for Compute prior to configuring the volumes.

    On Ubuntu, install nova-volume and lvm2.

    $ apt-get install lvm2 nova-volume


    On RHEL and derivatives, the nova-volume service should already be
    installed.


    ...

    View Slide

  7. PAST

    View Slide

  8. PAST

    View Slide

  9. PAST

    View Slide

  10. PAST

    View Slide

  11. Photo by Landon Hook on Unsplash

    View Slide

  12. PAST
    The documentation team are rapidly losing key contributors
    and core reviewers…[W]e now need to take a step back and
    realise that the amount of work we are attempting to
    maintain is out of reach for the team size that we have. At
    the moment we have 13 cores, of whom none are full time
    contributors or reviewers.


    ⸺ OpenStack manuals project migration spec

    View Slide

  13. PAST

    View Slide

  14. Past (where we’ve come from)
    Present (where we’re at)
    Future (where we’re going)
    PRESENT

    View Slide

  15. PRESENT

    View Slide

  16. PRESENT

    View Slide

  17. PRESENT
    ● openstackdocstheme
    ● oslo_config.sphinxext
    ● oslo_config.sphinxconfiggen
    ● oslo_policy.sphinxext
    ● oslo_policy.sphinxpolicygen
    ● reno.sphinxext
    ● os-api-ref
    ● zuul-sphinx
    ● ...

    View Slide

  18. PRESENT

    View Slide

  19. PRESENT
    doc/source/
    ├─ install/
    ├─ contributor/
    ├─ configuration/
    ├─ cli/
    ├─ admin/
    ├─ user/
    └─ reference/

    View Slide

  20. PRESENT

    View Slide

  21. PRESENT

    View Slide

  22. PRESENT
    $ tox -e docs

    View Slide

  23. PRESENT
    It’s not all roses though…

    View Slide

  24. Past (where we’ve come from)
    Present (where we’re at)
    Future (where we’re going)
    FUTURE

    View Slide

  25. Photo by Paolo Nicolello on Unsplash

    View Slide

  26. FUTURE

    View Slide

  27. FUTURE

    View Slide

  28. FUTURE

    View Slide

  29. Past (where we’ve come from)
    Present (where we’re at)
    Future (where we’re going)
    WRAP UP

    View Slide

  30. Working with Documentation,
    The OpenStack Way™
    How OpenStack Does Documentation
    Alex Settle
    Technical Writer, SUSE
    @dewsday
    Stephen Finucane
    Software Engineer, Red Hat
    @stephenfin
    Photo by Susan Yin on Unsplash

    View Slide