Mirantis OpenStack

  • Download

    Mirantis OpenStack is the zero lock-in distro that makes deploying your cloud easier, and more flexible, and more reliable.

  • On-Demand

    Mirantis OpenStack Express is on demand Private-Cloud-as-a-Service. Fire up your own cloud and deploy your workloads immediately.

Solutions Engineering

Services offerings for all phases of the OpenStack lifecycle, from green-field to migration to scale-out optimization, including Migration, Self-service IT as a Service (ITaaS), CI/CD. Learn More

Deployment and Operations

The deep bench of OpenStack infrrastructure experts has the proven experience across scores of deployments and uses cases, to ensure you get OpenStack running fast and delivering continuous ROI.

Driver Testing and Certification

Mirantis provides coding, testing and maintenance for OpenStack drivers to help infrastructure companies integrate with OpenStack and deliver innovation to cloud customers and operators. Learn More

Certification Exam

Know OpenStack? Prove it. An IT professional who has earned the Mirantis® Certificate of Expertise in OpenStack has demonstrated the skills, knowledge, and abilities needed to create, configure, and manage OpenStack environments.

OpenStack Bootcamp

New to OpenStack and need the skills to run an OpenStack cluster yourself? Our bestselling 3 day course gives you the hands-on knowledge you need.

OpenStack: Now

Your one stop for the latest news and technical updates from across OpenStack ecosystem and marketplace, for all the information you need stay on top of rapid the pace innovation.

Read the Latest

The #1 Pure Play OpenStack Company

Some vendors choose to “improve” OpenStack by salting it with their own exclusive technology. At Mirantis, we’re totally committed to keeping production open source clouds free of proprietary hooks or opaque packaging. When you choose to work with us, you stay in full control of your infrastructure roadmap.

Learn about Our Philosophy

OpenStack Project Technical Lead Interview Series #6: Anne Gentle, OpenStack Community Documentation Coordinator

on July 22, 2013

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.

3 comments

3 Responses

  1. Sergei

    Anne thank you for your work! Using maven to build large documentation it’s wonderful trick!

    if it possible can you please explain:
    1) why DocBook but not DITA? I understand that it’s question may be have no valuable answer. Both DITA and DocBook have about similar ability. But may be there are some thoughts why DocBook was chosen?
    2) What XML Authoring tools you using? Is it some CSS based (kinda ArborText, XMetaL, xmlmind)? Or you using “developer” XML tools?
    3) What tools you using for translations? Is there some automatization tools for tracking changes in the original language?

    August 19, 2013 20:35
  2. Anne Gentle

    Hi Sergei -
    Thanks for the comment. I’ll answer these questions below, they’re good ones! If you’re interested in a deep dive, join us at the Docs Boot Camp in September.

    1) why DocBook but not DITA? I understand that it’s question may be have no valuable answer. Both DITA and DocBook have about similar ability. But may be there are some thoughts why DocBook was chosen?

    Early on when I joined the project I did a “requirements” listing that’s still available on the OpenStack wiki at https://wiki.openstack.org/wiki/WebContentRequirements. I had a few reasons for choosing DocBook at the time:
    1. The API docs I was migrating from Rackspace were in DocBook and had a build system we could automate.
    2. The collaborators I hoped to work with from major distros such as Fedora worked with DocBook.
    3. The DocBook toolchain for output was open source and established.

    I had the same question, why not DITA, from an IBMer at a Design Summit a few summits back. The basic reasons are listed above — some existing source and the hope for collaborators.

    I have worked with both DITA and DocBook in the past so I know they are similar. In a way, we coach “DITA” by having contributors write “topically” with DocBook with concept/task/reference information typing and reusing sections and chapters as we see fit.

    2) What XML Authoring tools you using? Is it some CSS based (kinda ArborText, XMetaL, xmlmind)? Or you using “developer” XML tools?

    Oxygen generously offers floating licenses to open source projects, so many collaborators use those. Rackspace provides floating licenses for Oxygen for our employees. Rackspace also has a “rackbook” plugin for Oxygen that makes editing WADL much easier. That said, you can use any XML editor you like as long as you follow the line width and whitespace conventions so that diffs are easier to read. More here: https://wiki.openstack.org/wiki/Documentation/HowTo#Editor_Options and here: https://wiki.openstack.org/wiki/Documentation/Conventions.

    3) What tools you using for translations? Is there some automatization tools for tracking changes in the original language?

    OpenStack has an amazing, hard-working I18N team and Yung Ching Guo, Daisy, wrote Python scripts that “slice” the DocBook into translatable portions that are uploaded to Transifex. The tools for automation are documented here: https://wiki.openstack.org/wiki/I18n/Tools. I’m truly impressed with all the work they do.

    August 20, 2013 11:55
  3. Sergei

    Anne, thank you for your answers!

    Tools for automation translation you use is really amazing! I’m impressed too!

    Oxygen is my favourite XML editor and authoring tool too. It’s very sad that there is no any usable open source XML Authoring tool. You use only open source fonts but have to use closed source XML Authoring tools.

    Unfortunately Mountain View, CA is too far for me (Tomsk, Siberia, Russia) :)

    August 21, 2013 05:02

Some HTML is OK


or, reply to this post via trackback.