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

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

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

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

    View full-size slide

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

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

  7. Photo by Landon Hook on Unsplash

    View full-size slide

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

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  12. PRESENT
    $ tox -e docs

    View full-size slide

  13. PRESENT
    It’s not all roses though…

    View full-size slide

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

    View full-size slide

  15. Photo by Paolo Nicolello on Unsplash

    View full-size slide

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

    View full-size slide

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