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

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