OpenStack Project Technical Lead Interview Series #6: Anne Gentle, OpenStack Community Documentation Coordinator
This post is the sixth in a continuing series of interviews with OpenStack Project Technical Leads on our Mirantis blog. Our goal is to educate the broader tech community and help them understand how they can contribute to and benefit from OpenStack. Naturally, these are opinions of the interviewee, not of Mirantis.
This interview is with Anne Gentle, OpenStack Community Documentation Coordinator.
Mirantis: Would you please introduce yourself?
Anne Gentle: I work on OpenStack documentation full time at Rackspace, and I actually was the second hire Rackspace did for the OpenStack project. It was the greatest match I could ever wish for. I wrote a book in 2009 about how to do community collaborative documentation, and I had volunteered on a lot with open source docs projects. This job showed up in my backyard in Austin, Texas, and I just jumped at it.
Q: What is the major difference between open source and closed source documentation?
A: The first big difference is interest in openness everywhere, from authoring to publishing to display. I was even asked if all of our fonts are open source in the first few weeks I started! Our toolchain is open to anyone to author with or tinker and reuse themselves. The second difference is in licensing. In a closed source environment, the documentation is very legally bound to provide a certain service-level or billing agreement. The idea behind open collaborative docs is that anyone can edit them and, in some communities, the ethos is very involved in the attribution of content. That's a really good case for creative commons licenses.
So there's a whole range, but a lot of it is around licensing and the freedom of the content, I also believe there's a lot of interesting innovation going on in open source. For many of the same reasons you would do open source coding, I think there's a similar draw for open source docs.
Q: What makes open source documentation so special?
A: There is a need to have a lot of discipline around documentation, and open source surprisingly lends itself to that. Open source, especially projects that try to tie docs to code as much as possible, are actually going to be very disciplined in their processes. You log a bug against the docs. People know they can come and pick up a doc bug.
Over time the wikis have become more disciplined and are content management systems, and the true free wiki, based on Ward Cunningham’s original idea, is still a valuable mechanism and a valuable idea about content. It's just that I'm more drawn to innovative authoring sessions like a book sprint than wikis. I also am drawn to treating docs like code, finding ways to auto-generate documentation that still helps people but that keeps up with the code.
Q: What principles are applied in open source documentation?
A: Open source docs is a disciplined, yet diplomatic process. You have to find ways to introduce a process to your documentation, but be very diplomatic, because people bring content, they really like their content, and they want it to live on in some official capacity.
One of the most interesting methods is Book Sprint. You gather a team of writers and have them share all of that knowledge, try to get it out of their brains, onto some kind of organized structure. The tool used there is called Booktype, and the great thing is that Sourcefabric can maintain an instance for you.
For the Operations Guide, even though all the people who were at that sprint knew how to use our XML-based toolchain, they were able to immediately use the Booktype tool, and then, after the sprint, once all the content had calmed down and we felt it was very solid, we took it into the XML-based toolchain.
What's cool about the XML-based toolchain is that it's identical to what O'Reilly uses. The beauty of the XML is it lets us have chunks of content that are reusable, that we can tag, that a translator never would translate otherwise. Out of that we get multiple outputs. We can get ePub if we want. And then, you just learn as you work with content over years that this kind of XML slicing and dicing is the best way to wrap your arms around a large body and keep it organized.
The docs fit right into the code methods. We use Git. We use Gerrit. We review each other's stuff side by side, just like you would a code commit. You have to build it locally, make sure it passes the build, make sure it validates. Jenkins tests all our stuff and auto-publishes it.
One of the principles is that you don't want to anger or frustrate people with your approach to documentation. People look for groups that they recognize themselves in. You might say. “Oh. Those aren’t my people,” or, “That's not my interest area.” One of the principles of open source documentation to me is that this is personal collaboration. You want to feel like you belong, you understand their goals.
I just try to match up what jobs I can give to meet your skillset so you won’t get frustrated and leave. What tasks are actually interesting for you from a technical standpoint? I think that's just one of the principles of open source—people matching to tasks—and it's very important.
Q: Do you see any differences in the way people contribute to OpenStack documentation depending on their background?
A: For the Grizzly release, 50 percent of all of the edits, except for the API books, were done by three people, one of them being me. [laughing] We're really trying to look towards more people doing more.
But the really interesting thing about that number is that we had 79 total contributors. These people did six or eight patches, but they might have specialty knowledge. They knew how to configure Cinder, what needed to be done, what piece of content I could write to make that happen.
You need a core group that knows every bit that's in the database, or in keystone, but you also need these specialists. As the project grows and grows it’s important how to prioritize whether to stay at that top level or work project by project by project.
There are admin manuals per project, but they still have to tell you how to install and configure things. The storage manual has a whole bunch of info known only by driver people. It's really tough to know whether to continue to maintain admin manuals per project. There are now ten projects and two more under consideration. We can't really maintain ten admin manuals, especially when some interact together. We're investigating what's the best approach, even to a) get contributors, but also b) help them find what to work on.
Another thing is that we want developers writing for developers and so on. What the Book Sprint methodology brought out for me is that the Operations Guide rocked because those guys do operations day in, day out. And the same thing I'm seeing with the security hardening guide; those guys think, breathe, and sleep it.
Q: What does keep people back from contributing and participating in documentation?
A: I think that a lot of people, once they see we use GitHub, Gerrit, and XML, they might go: “Wow, not my specialty!”...and they step away. I have onboarded literally dozens of people just going through the CLA process. You have to be pretty patient to get through that because you're a doc writer or you want to fix a typo, but you gotta go all the way through the CLA. And I'm actually pretty opinionated about that. I think I would rather have doc contributors who are OpenStack Foundation members and are embedded in the open source community than just kind of walk up and walk away kind of people.
And then, lastly, just the sheer knowledge and hardware and technical requirements might really scare people off.
Q: What is the route that someone typically would take from being a freshman to a documentation pro at OpenStack?
A: There's a couple of routes I can think of. Definitely do some kind of hands on things with OpenStack and then see which of those audiences you fit into. Then start by really examining the documentation: “Did it answer my questions? Are there some pieces that are missing?” And try to make sure you have your user or developer hat on when you approach a document.
I think that the user groups are starting to do really cool things. Sean Roberts and Colin MacNamara are leaders of San Francisco Bay User Group and they're running a little workshop about how to contribute to the docs because they have people who want to learn OpenStack, and a good way to learn is by picking up on the tools and picking up on the docs. And a great way to learn is to write things down as you go.
We also have a lot of student groups that are like, “I think documentation is something I'd be really interested in as a good starting point.” For them we have something like a to do list. See if there's a preface in the book. Run a spell check. Make sure that the capitalization is correct according to our conventions etc.
I also think people could do reviews. I've had people, they could just mail me a PDF that they've marked up. That would be totally fine. Anything to just start reading, start reviewing, figure out what you could do to get from looking at this giant pile of docs to, “Oh, here's a piece that I really identify with.”
Q: Can you tell us a little bit about your documentation boot camp?
A: Our Bootcamp is a way to build the bonds between the current contributors and also to encourage more people to become core doc contributors. We’re holding it in Mountain View, California, September 9 and 10.
We'll just walk through all the tools and processes to give everyone a comfort level with the tools. For processes, we’ll answer questions like, “Do I write a blueprint for this? Or is this just a bug? How do I know whether to do this or the other? How do I know what tool I can use to validate? What the heck is Maven? When I add a new book, what do I have to do to get it to be published? How do I troubleshoot when I made a change but I don't see it on the website at all?” All of these things are day one.
And then day two is going to be more BarCamp-like, where we talk about things that you can work on. You don't have to do them that day, but a lot of like, “Here's what we can actually do with this knowledge we just gained.” Day two can be a total doc bug-squashing day. The main idea is to onboard new contributors in such a way that they will be on a fast track to becoming core.
Q: How about translations?
A: A true value statement to me is that one day there will be an OpenStack manual written in French and instead of translating English to French, we will translate it to English. I never feel like we should always approach documentation as English is first language. I'm bringing my own personal opinion, but I don't believe that we should call only English manuals the first one you ever write for OpenStack.
What translation of documentation comes down to is prioritizing. We prioritize that the operations guide get translated right away because there was a lot of demand. Daisy, the translation coordinator, actually e-mailed me last week and asking what would be the next one. And I said, “Honestly, I'd like to see that user guide translated and probably after that the Admin User Guide. Try to get both the operator audience in their own language and the admins in their own language.”
Q: Thank you for your time.
A: Thank you.
