On Writing, Tech, and Other Loquacities

The collected works of Lana Brindley: writer, speaker, blogger

OpenStack Mitaka Summit – Docs Wrapup

Leave a comment

Tokyo is a city that is all about contrast. From the neon lights of Shibuya and Akihabara (“Electronics Town”), to the shrines and temples dotted in green spaces around the city, old and new Japan come together in Tokyo in a surprisingly harmonious way. While OpenStack Summit, like the people of Tokyo, is focused on new technology and moving into the future, it is important to note the atmosphere of community, fellowship, and camaraderie that underpins the conference.

Tokyo_CityLights

I am privileged enough to be the documentation PTL for Mitaka, having taken over the reins from Anne Gentle after the Kilo cycle. This time around, we have three main priorities to achieve, and I think it’s a  lovely blend between the technical and the community.

First of all, we will focus on improving the usability of our documentation, making it easier to navigate the docs site and find relevant information quickly. The main way we want to address this is through a different model of data typing, and moving away from a role-based architecture towards a task-based one. This is easier to do for some guides than others, of course, and we intend to start with the user guides. The other component of this is reorganising the index page, and adding some more guidance on what each book is about. You should start to see those changes rolling in shortly.

We also want to continue converting our books to RST. A lot of our books have already been converted, but we still have quite a few to go, and determining which books are to be converted in each release and who is responsible for doing so can take quite a bit of planning. This time around, we’re looking at the Architecture Design Guide, the Operations Guide, and the Configuration Reference Guide.

Finally, a fairly small thing that should have a big influence on our work is tweaking the way the docimpact tool works. At the moment, it creates a lot of noise in our bug queue and makes it harder for us to find the real work that needs to be done. By changing the way this tool operates, we hope it to make it much more responsive and useful both for the docs team, and for the OpenStack developer community.

Tokyo_Shrine

This release is about having docs work more efficiently and effectively as part of the OpenStack development community. With OpenStack moving to the big tent, we need to reevaluate which projects we document, how we go about communicating with other development teams, and we need to ensure we’re being good community citizens. I also want to ensure we’re working closely with enterprise writing teams, and valuing the input that our corporate contributors provide to the documentation.

Liberty was my first release as Docs PTL, so I’m still learning what makes a good release. It was great to hear feedback from the docs team on what went well and what didn’t go so well, so I can learn from this to improve in Mitaka. I’m very grateful to have a team that has supported me in my new role, and I am honoured to be leading them again into the next release.

Finally, we always need docs contributors. If you are a technical writer, then we have plenty of projects that can use your writing expertise. If you’re a developer, even if you don’t think you’re a good writer, then we could definitely use your technical prowess to test and improve our documentation. Remember, the documentation is developed exactly like code within the OpenStack system, so if you’re an ATC, you already have the skills required to contribute, and to improve the docs for all our users.

Share

Leave a Reply