How you can help refresh OpenStack’s Documentation site

If you’ve checked out the OpenStack Documentation site recently, you may have noticed a new look. The refreshed design of the landing page is the beginning of an ongoing overhaul. The site is, however, open under construction and people are already applauding the refresh. The move to a simpler markup language will go a long way to helping OpenStack contributors work on the documentation that matters to them.

Superuser talked to OpenStack’s documentation technical lead Anne Gentle to find out more about how the design will affect contributors and how you can help get the site ready for the April relaunch.

What will the new site do for contributors?

My philosophy about documentation is that developers should write for developers, operators should write for operators and users should write for users.

The change from XML to RST (ReStructured Text) will enable more people to work on the books that matter to them. The new site won’t require any special tools or knowledge of XML. RST is a very simple markup language, like Wiki-text. The simplified markup makes it easier to compare changes side-by-side, without adding in the tags that you get with XML. The fact that you can make updates quickly should help keep the documentation fresh.

Overall, the documentation site is more welcoming and helps people find the information they need quickly. Previously, it was harder to see what release you were looking at, and whether that documentation suited your purpose.

In the redesign, there are very specific features (when it was last built, what release it’s for) and these markers will help people realize whether the documentation is what they need or not. Search is also better integrated, so that you can find Wiki pages, .docs, etc.

You can also suggest an edit to any page – there’s a link on each page that either lets you log bug or go ahead and patch it yourself.

bqrwuod2sytf2rnxznx2
The new sites features bug reporting links on each page.

Where are you now with the new design?

The landing page is published, and we’re working through the migration and continuous integration, including translation, from now until to first week of April, so that’s newsworthy!

Tell us more about what needs work.

The docs site remodel means we’ve created a new Sphinx theme. Sphinx is a document generator written for Python that converts the RST source to HTML. That still means there’s some CSS and JavaScript troubleshooting to do, so I need Python developers who understand Sphinx to take care of the bugs that I’m logging.

For instance, there’s a bug where a plus icon is added above a numbered list item that has a nested numbered list item. I haven’t dug into that one too far, but I was able to fix a bug where an extra line number was added to every code sample!

Here’s a list of ongoing bugs that people can work on.

What about the migration?

For migrating to RST we have a script, but there’s still a lot of cleanup needed there, too. We have a signup page on the wiki with instructions for how to migrate from DocBook to RST: https://wiki.openstack.org/wiki/Documentation/Migrate

What help do you need with the translations?

That requires some Python knowledge, too, and we’re working with our i18N team who has deep knowledge of the toolchain and Transifex. We’re pretty sure we know how to make the files that Transifex needs, it’s just a matter of automating that.

Our translation toolchain is pretty amazing – it already auto-posts updated translations and puts files back into the repo for building and publishing to the web. We’re doing a phased approach with the user guides first. (The ops guide and the install guide are currently the most translated but those are not part of this migration phase.)

Right now, the user guide is not published completely in any language, but Japan and China are working their way through it. The threshold for linking to a translation page is 8 to 10 percent so they are above that threshold for certain.

I’d like to have the complete toolchain done by April 9, but all of this work can happen concurrently. That’s when we’d like to be flip the switch from XML to RST. There’s a great wiki page about translations at https://wiki.openstack.org/wiki/Translations if you’d like to get involved.

Last but not least, how did those cool avatars get on the landing page?

Wes Wilson and Todd Morey came up with that idea. At the Design Summit in Paris, the doc team got together and reviewed both the landing page and the content page – and the feedback was: “Let’s not get just a guy, but find a way to get a woman up there, too.” The image rotates, and we can certainly keep adding people. All we have to do is get more images and add them in.
Maybe we’ll have to start an avatar-as-a-service?