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. 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. Past (where we’ve come from) Present (where we’re at) Future

    (where we’re going) AGENDA
  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?
  4. Past (where we’ve come from) Present (where we’re at) Future

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

    (where we’re going) PAST
  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> ...
  7. PAST

  8. PAST

  9. PAST

  10. PAST

  11. Photo by Landon Hook on Unsplash

  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
  13. PAST

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

    (where we’re going) PRESENT
  15. PRESENT

  16. PRESENT

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

    oslo_policy.sphinxpolicygen • reno.sphinxext • os-api-ref • zuul-sphinx • ...
  18. PRESENT

  19. PRESENT doc/source/ ├─ install/ ├─ contributor/ ├─ configuration/ ├─ cli/

    ├─ admin/ ├─ user/ └─ reference/
  20. PRESENT

  21. PRESENT

  22. PRESENT $ tox -e docs

  23. PRESENT It’s not all roses though…

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

    (where we’re going) FUTURE
  25. Photo by Paolo Nicolello on Unsplash

  26. FUTURE

  27. FUTURE

  28. FUTURE

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

    (where we’re going) WRAP UP
  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