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

8fbd28ad59a1aa317a5ec175b0778359?s=128

Stephen Finucane

April 30, 2019
Tweet

Transcript

  1. 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
  2. 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?
  3. 6.

    PAST <section xml:id="install-nova-volume" 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"> <title>Install nova-volume on

    the cloud controller</title> <para>While nova-volume does not directly use the network, you must have networking set up for Compute prior to configuring the volumes. </para> <para>On Ubuntu, install nova-volume and lvm2.</para> <screen os="ubuntu"> <prompt>$</prompt> <userinput>apt-get install lvm2 nova-volume</userinput> </screen> <para os="centos;rhel;fedora"> On RHEL and derivatives, the nova-volume service should already be installed. </para> <para> ...
  4. 7.
  5. 8.
  6. 9.
  7. 10.
  8. 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
  9. 13.
  10. 15.
  11. 16.
  12. 17.

    PRESENT • openstackdocstheme • oslo_config.sphinxext • oslo_config.sphinxconfiggen • oslo_policy.sphinxext •

    oslo_policy.sphinxpolicygen • reno.sphinxext • os-api-ref • zuul-sphinx • ...
  13. 18.
  14. 20.
  15. 21.
  16. 26.
  17. 27.
  18. 28.
  19. 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