Category Archives: techpubs

community techpubs tools

Tearing down obstacles to OpenStack documentation contributions

Rip. Shred. Tear. Let’s gather up the obstacles to documentation contribution and tear them down one by one. I’ve designed a survey with the help of the OpenStack docs team to determine blockers for docs contributions. If you’ve contributed to OpenStack, please fill it out here:

https://docs.google.com/forms/d/136-BssH-OxjVo8vNoOD-gW4x8fDFpvixbgCfeV1w_do/viewform

barriers_sameleighton
I want to use this survey to avoid shouting opinions and instead make sure we gather data first. This survey helps us find the biggest barriers so that we can build the best collaboration systems for documentation on OpenStack. Here are the obstacles culled from discussions in the community:

  • The git/gerrit workflow isn’t in my normal work environment
  • The DocBook and WADL (XML source) tools are not in my normal work environment
  • My team or manager doesn’t value documentation so we don’t make time for it
  • Every time I want to contribute to docs, I can’t figure out where to put the information I know
  • When I’ve tried to patch documentation, the review process was difficult or took too long
  • When I’ve contributed to docs, developers changed things without concern for docs, so my efforts were wasted
  • Testing doc patches requires an OpenStack environment I don’t have set up or access to in a lab
  • I think someone else should write the documentation, not me
  • I would only contribute documentation if I were paid to do so

Based on the input from the survey, I want to gather requirements for doc collaboration.

We have different docs for different audiences:

  • cross-project docs for deploy/install/config: openstack-manuals
  • API docs references, standards: api-site and others

These are written with the git/gerrit method. I want to talk about standing up a new docs site that serves our requirements:

Experience:
Solution must be completely open source
Content must be available online
Content must be indexable by search engines
Content must be searchable
Content should be easily cross-linked by topic and type (priority:low)
Enable comments, ratings, and analytics (or ask.openstack.org integration) (priority:low)

Distribution:
Readers must get versions of technical content specific to version of product
Modular authoring of content
Graphic and text content should be stored as files, not in a database
Consumers must get technical content in PDF, html, video, audio
Workflow for review and approval prior to publishing content

Authoring:
Content must be re-usable across authors and personas (Single source)
Must support many content authors with multiple authoring tools
Existing content must migrate smoothly
All content versions need to be comparable (diff) across versions
Content must be organizationally segregated based on user personas
Draft content must be reviewable in HTML
Link maintenance – Links must update with little manual maintenance to avoid broken links and link validation

Please take the survey and make your voice heard! Also please join us at a cross-project session at the OpenStack Summit to discuss doc contributions. We’ll go over the results there. The survey is open until the first week of May.

community techpubs work writing

OpenStack Operations Guide Mini Sprint

oreilly-openstack-ops-guide

We held a two-day mini-sprint in Boston at the end of January to update the OpenStack Operations Guide. You may remember the first five-day sprint was in Austin in February 2013. This time, the sprint was shorter with fewer people in Boston and a few remote, but we had quite specific goals:

  • Update from Folsom to Havana (about a year’s worth of OpenStack features)
  • Roadmap discussion about nova-network and neutron, the two software-defined networking solutions implemented for OpenStack
  • Add upgrade instructions from grizzly to havana
  • Implement and test the use of parts to encapsulate chapters
  • Address editor comments from our developmental editor at O’Reilly
  • Add a reference architecture using RedHat Enterprise Linux and neutron for networking

Some quick wins for adding content were:

We added and updated content like mad during the two days:

The two toughest updates are still in progress, and our deadline for handover to O’Reilly is this Wednesday. The first tough nut to crack was getting agreement on adding an example architecture for Red Hat Enterprise Linux. We are nearly there, just a few more fixes to go, at https://review.openstack.org/#/c/69816/. The second is testing the upgrade process from grizzly to havana on both Ubuntu and RedHat Enterprise Linux. That’s still in progress at https://review.openstack.org/#/c/68936/.

The next steps for the O’Reilly edition are proofreading, copyediting, and indexing over the next six weeks or so. I’ll be keeping the O’Reilly edition in synch with our community-edited guide. As always, anyone in the OpenStack community can contribute to the Operations Guide using the steps on our wiki page. This guide follows the O’Reilly style guide rather than our established OpenStack documentation conventions. I’m looking forward to a great future for this guide and we’re all pretty happy with the results of the second mini-sprint.

Thanks to everyone making this a priority! Our host at MIT was Jon Proulx joined by Everett Toews who braved airport layovers and snow, and Tom Fifield who wrote the most patches despite a complete lack of sleep. Joe Topjian worked on edits for months leading up and has been tireless in making sure our integrity and truth lives on through this guide. Thanks too to the the hard working developmental editor at O’Reilly who offered lunch in Boston, Brian Anderson, joined by Andy Oram. David Cramer got DocBook parts working for us in time for the sprint. Summer Long worked long and hard on the example architecture for RedHat. Our remote reviewers Matt Kassawara, Andreas Jaeger, and Steve Gordon were so valuable during the process and ongoing. Shilla Saebi gave some nice copyediting this past week. What an effort!

community content strategy techpubs tools

A Few of my Favorite Things for 2013

tumblr_m8lsqnjijt1qgx2ojo4_250

This year has been filled with interesting finds, discoveries, and productivity. Plus oxford commas! Here are my favorite things for 2013.

The Hunger Games trilogy, because it’s like a window into a mind of a smart writer who writes with purpose.

The Documentation chapter of the Developer Support Handbook has to be one of my very favorite things I discovered this year. I’m on the Developer Relations Group team at Rackspace and this is a great handbook for all of our team.

Animated GIFs, pronounced jifs, am I right? OpenStack Reactions cracks me up.


Grace Hopper Conference by the Anita Borg Institute, especially the Open Source day, and the GNOME Outreach Program for Women which OpenStack started participating in this year. Women in technology are my favorite!

The Houzz App on my Android tablet for eye candy while messy remodeling was actually happening. Plus it’s the best content remix site I’ve seen in a while, more targeted than Pinterest.

Photo kids

Probably the best photo of my kids this year, I make it a favorite because at their ages it’s difficult to get one of the both of them.

OpenStack Docs Boot Camp

OpenStack Security Guide book sprint, read it at http://docs.openstack.org/sec/.

oreilly-openstack-ops-guide

OpenStack Operations Guide book sprint, now an O’Reilly edition, read it at http://docs.openstack.org/ops/.

How about you? What are some of your favorite things from this past year?

techpubs work writing

Who Wrote OpenStack Havana Docs?

I know, I know, OpenStack is too obsessed with statistics for contributors. I agree! I want to rise above it but the trend release-over-release for docs is way too tempting for me in my research lab for documentation. So allow me to indulge in some analysis that is similar to my post about this last release, Who Wrote OpenStack Grizzly Docs? Remember? We had 79 docs contributors overall, with 3 of us writing half of the changes for Grizzly. This time we had 130 docs contributors with 7 of us writing just over half the changes in overarching install/config/deploy/operations guides. Progress! We also had at least three supporting companies hire writers dedicated to OpenStack upstream docs. Full of win. I love having OpenStack job postings to offer great tech writers.

Worcester Terrace

We added 100,000 lines more than last release. What? Yes, it’s true. Much of that is from our autodoc efforts, pulling all 1500 configuration options directly from the code, but that’s a compelling number to share.

I ran the same scripts as last time to maintain consistency. All these stats are from the tools that aren’t being maintained any more from openstack-gitdm.

Here are the numbers for the openstack-manuals repository only:

Processed 966 csets from 130 developers
92 employers found
A total of 187524 lines added, 275056 removed (delta -87532)

Developers with the most changesets
 Andreas Jaeger 233 (24.1%)
 annegentle 89 (9.2%)
 Tom Fifield 70 (7.2%)
 Diane Fleming 70 (7.2%)
 Christian Berendt 65 (6.7%)
 Sean Roberts 44 (4.6%)
 Stephen Gordon 41 (4.2%)
 Summer Long 21 (2.2%)
 Lorin Hochstein 20 (2.1%)
 nerminamiller 17 (1.8%)
 Gauvain Pocentek 15 (1.6%)
 Emilien Macchi 15 (1.6%)
 Colin McNamara 14 (1.4%)
 Shaun McCance 13 (1.3%)
 Deepti Navale 11 (1.1%)
 Phil Hopkins 9 (0.9%)
 Aaron Rosen 8 (0.8%)
 Kurt Martin 8 (0.8%)
 Scott Radvan 7 (0.7%)
 Edgar Magana 7 (0.7%)
 Covers 80.434783% of changesets

This is another interesting data set:

Employers with the most hackers (total 136)
Red Hat                     12 (8.8%)
IBM                         12 (8.8%)
Rackspace                    8 (5.9%)
HP                           7 (5.1%)
Nicira                       4 (2.9%)
Mirantis                     4 (2.9%)
SUSE                         2 (1.5%)
Yahoo!                       2 (1.5%)
eNovance                     2 (1.5%)

I also ran these same stats for the api-site repository, where the API user docs are sourced. These docs are still quite different from a contributor and sourcing standpoint and I’m not sure why. Rackspace dedicating Diane Fleming has made a huge difference here, think of what we could do with one more dedicated API doc writer? Ok, we can’t clone Diane, but think of the possibilities.

Developers with the most changesets
Diane Fleming 46 (58.2%)
annegentle 5 (6.3%)
Cyril Roelandt 2 (2.5%)
Kersten Richter 2 (2.5%)
Brian Rosmaita 2 (2.5%)
Rupak Ganguly 2 (2.5%)
QingXin Meng 2 (2.5%)
ladquin 2 (2.5%)
dcramer 2 (2.5%)
Employers with the most hackers (total 23)
Rackspace 5 (21.7%)
IBM 5 (21.7%)
Red Hat 2 (8.7%)

I’m also a web analytics hound. What docs were the most accessed during the lead-up to the Havana release? Here are the top five:

  1. Swift Developer site
  2. Install Guides (Basic and Deploy, both Ubuntu and RedHat/Fedora/Centos)
  3. API Quick Start
  4. OpenStack Operations Guide
  5. Getting Virtual Machine Images page from the OpenStack Compute Administration Guide

To me, these stats show that we’re doing the right things such as dedicating a contractor to the install guide. Thank you Cisco. We still have areas to improve, such as API docs and ensuring end-user docs are a top priority. Our readers are definitely after both deployment and consumption of OpenStack clouds.

techpubs work

OpenStack DocImpact Flag Walk-through

In our unconference sessions at OpenStack Docs Boot Camp, we talked about integration with development, the DocImpact flag, and I came up with these guidelines for what a DocImpact commit message should contain. I wanted to talk about it here on my blog before posting to the wiki to see if I’m missing anything crucial.

  • Who would use the feature?
  • Why use the feature?
  • What is the exact usage for the feature? For a CLI call, provide examples of all the parameters the patch includes.
  • Does the feature also have permissions/policies attached?
  • If it is a configuration option, which flag grouping should it go into? (Defaults and a description are already required by their gate test on nova.)

I’ll walk through it with a DocImpact bug I worked on today titled “havana: nova Add force_nodes to scheduler hints“. I went on IRC to ask the developer the questions and got these answers:

  • Who would use the feature? Only administrators using the baremetal driver for nova.
  • Why use the feature? Baremetal is used when doing high-performance computing or standing up clouds from baremetal. Turns out, this driver is getting moved out of nova soon, and spans the realm of Heat + TripleO, and still a work in progress, but getting really close. HP is using it already to get compute nodes ready for action. This specific feature is used to specify exactly which node to send the next set of commands to.
  • What is the exact usage for the feature? For a CLI call, provide examples of all the parameters the patch includes. It’s a call on the nova boot command with the –availability_zone flag, and you can have nova boot –availability_zone=zone:host,node. You have to get the node in the form of a UUID.
  • Does the feature also have permissions/policies attached? In this case, it turns out some API features didn’t land in Havana, and so if you have to use a UUID for a baremetal node, then you have to do a SQL database call in order to get the UUID. This usage requiring database access is sort of “ugly” so I’m still trying to decide what to do with it. Also, I recall a lot of discussion around scheduler hints passed in with the –availability_zone flag so I’m still working on this doc bug. It would help greatly if the developer had done some of this end-user thinking up front, but he couldn’t have known back in May that the API changes wouldn’t land in September.
  • If it is a configuration option, which flag grouping should it go into? (Defaults and a description are already required by their gate test on nova.) For the baremetal driver, we already have docs for the configuration reference, but it was a good check to do. I found that the wiki page had a redirect to a simpler page name, so I’ve included that in my patch.
techpubs work writing

Discipline and Diplomacy: Docs in the Open

In open source, all sorts of interesting connections happen. In open source documentation, an even more narrowly defined group of folks connect the dots for others. Recently I was interviewed by Mirantis, an OpenStack services startup, about my involvement with OpenStack documentation. They’re doing a series of interviews with the technical leads in OpenStack. We had a good time talking, and here’s an excerpt with a link to the full interview. I wanted to share it for my readers to see my open source views as a snapshot.

Mirantis: Can 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 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 open-ness 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 re-use 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. Read more…

community techpubs work writing

Book Sprint for OpenStack Security Guide

The legendary book sprint method has come through again! This past week in a bunker, I mean, secure location near Annapolis, a team of security experts got together to write the OpenStack Security Guide. I’m pleased as can be to have the privilege of sharing the epub with you here and now, the evening of the fifth day!

Download the epub file and start reading. One of the goals for this book is to bring together interested members to capture their collective knowledge and give it back to the OpenStack community.

This cover gives you a glimpse of the amazing feat this team pulled off. We’ll have HTML and PDF in the next couple of weeks to fulfill your multi-output consumption wants and needs. For now, fire up your ereader, and start reading! The team wants your input.

content strategy techpubs tools writing

Documentation as Conversation with CSS

Three types of speech balloons: speech, thought, scream.

I love to explore new ways of conveying technical information, and I’m interested in documentation as conversation. Last year I wanted to convey a “side note” on each page of a Sphinx site, as if the page were talking to you. I needed to let people know that there are additional documentation pages available. So, I went looking for a CSS design that would let me put the note into a particular tag and style as I like. I found it at Pure CSS speech bubbles. The humorous part was figuring out what speech bubbles are also called so I could do a Google search. Speech balloons? Dialog balloons? Word balloons? I never did come up with balloon but somehow found bubble.

For Sphinx sites, which are built from RST (ReStructuredText), you use a layout.html file in a _theme folder with your .rst source files. This templating is explained in more detail on the Sphinx documentation site at http://sphinx-doc.org/. In this case, the p tag is styled with css classes. Here’s what the HTML looks like:

<p class="triangle-border right">
Psst... hey. You're reading the latest content, 
but it's for the Block Storage project only. 
You can read <a href="http://docs.openstack.org">
all OpenStack docs</a> too.</p>

The CSS is much more involved, giving borders and rounded edges and putting that little triangle to indicate the speech. You can see it embedded in the Sphinx framework at tweaks.css. You can select a border color to match the rest of your page. Here’s the resulting HTML output. Speech bubble example

You may have seen the trend towards comic books or comics to explain technical topics, such as the one for Google Chrome at http://www.google.com/googlebooks/chrome/. There are drawn comic characters explaining the browser design considerations throughout, with speech bubbles, hand waving, folded arms, lots of body language expressed throughout. This simple side bar doesn’t attempt that level of engaging content, but it’s a playful way to let people know there’s more than a single page for OpenStack docs. What do you think about such techniques, are they playful and harmless or sloppy and annoying?

techpubs tools writing

Who Wrote OpenStack Grizzly Docs?

Sneaking a peek at the numbers for documentation along with the code should show us pointers about docs keeping up with code. As I suspected, there were about three major contributors to the operations manuals that span all the projects, and about three major contributors to the API docs. Also not a big surprise, I am the major contributor to both. My spidey sense felt it but I had a real gut check with the actual data.

timsamoff_no3

What’s difficult about this data analysis at this time is that we still need to release the docs even while we plan for the next six months. What I really want to do is look at the past six months and all the amazing work and accomplishments we have seen. The growth has been great and the fantastic feat of the Operations Guide really topped off my year. But we are still lacking enough strong doc contributors to keep up with the pace of code growth.

First, let’s look at the OpenStack code analyzes. The last six months showed 517 contributors. For example, Object Storage grew their new contributors by over 35 people which is probably doubling the involvement. Our Infrastructure team continues to raise the bar for helping us slam in more and more bits as fast as our little cloud servers can slam them. Here’s Monty Taylor’s report:

OpenStack code patches

                        Essex   Folsom  Grizzly
Patches Uploaded        11036   17986   29308
Changes Created         5137    5990    12721
Changes Landed          4235    4978    10561
Avg patches per Change  2.6     3.6     2.7
Landing Percentage      82%     83%     83%

What I want to do here is provide similar data that shows the growth of the project relative to the docs. I’m using the openstack-gitdm project to run the numbers for the documentation repos. There are eight in total but I’m just going to look at the top two, openstack-manuals and api-site. The openstack-manuals repository holds the install, configuration, adminstration, high availability, and operations guide. The api-site repository holds the building blocks for the API reference page, the API Quick Start, and other API guides (but not the API specs).

Here’s a listing of all the OpenStack doc repositories:
openstack/openstack-manuals – for operators and deployers, docs.openstack.org
openstack/api-site – for API consumers, api.openstack.org
openstack/compute-api
openstack/image-api
openstack/object-api
openstack/netconn-api
openstack/volume-api
openstack/identity-api

These are the types of statistics I want to know about doc contributions.
Number of doc contributors: 79. This is a great value.
Number of new doc contributors: 27. I like this from a growth standpoint.
Number of doc contributions: 512. There were 435 doc changes within openstack-manuals during the grizzly release, and 429 during the folsom release. Compared to over 12,000 code changes I instinctively know this wasn’t enough doc update. While we do have a good base set of docs, they are getting a bit crufty and we want to address that in the Havana release.

Number of employers: 49 (up from 37 last release). This is a high number. The highest doc contributing employer is Rackspace during the Grizzly release.

So, what about quality? The most bugs fixed by a doc contributor is 45 (well over half) by Tom Fifieldt. Tom is a great doc bug triage expert and I don’t know what we’d do without him.

How about what’s the top docs being read? The most read books are the Ubuntu Install and Deploy and the API Quick Start followed closely by the Identity 2.0 API Spec (wow that surprised me).

Here’s the reported data from openstack-gitdm. Thanks to Daniel Stangel for helping me retrieve this data. One hidden contributor is Jon Proulx, who wrote lots of the Operations Guide. Everett Toews also contributed a lot to the Operations Guide but won’t show up here. This omission leads me to suspect there may be other “ghosts” writing OpenStack docs, but I think the main point is, the top three shown below are far ahead of the fourth, fifth, and sixth-highest doc contributors.

Processed 435 csets from 79 developers
49 employers found
A total of 87457 lines added, 26085 removed (delta 61372)

Developers with the most changesets
Tom Fifield                 99 (22.8%)
annegentle                  86 (19.8%)
Lorin Hochstein             46 (10.6%)
Emilien Macchi              17 (6.0%)
atul jha                    11 (2.5%)
Mate Lakat                  10 (2.3%)
Diane Fleming                9 (2.1%)
dcramer                      8 (1.8%)
Aaron Rosen                  8 (1.8%)
gongysh                      6 (1.4%)
Ed Kern                      6 (1.4%)
Eduardo Patrocinio           6 (1.4%)
Alvaro Lopez Garcia          5 (1.1%)
Kurt Martin                  4 (0.9%)
Dan Wendlandt                4 (0.9%)
Razique Mahroua              4 (0.9%)
Gary Kotton                  4 (0.9%)
Dolph Mathews                4 (0.9%)
Christophe Sauthier          3 (0.7%)
Covers 80.459770% of changesets

Developers with the most changed lines
daisy-ycguo               37578 (39.9%)
Diane Fleming             19381 (20.6%)
annegentle                7624 (8.1%)
Tom Fifield               3126 (3.3%)
Lorin Hochstein           2757 (2.9%)
John Griffith             2390 (2.5%)
gongysh                   2169 (2.3%)
zhangchao010              2036 (2.2%)
Mate Lakat                1927 (2.0%)
Emilien Macchi            1684 (1.8%)
Navneet Singh              970 (1.0%)
Alvaro Lopez Garcia        647 (0.7%)
Brian Rosmaita             580 (0.6%)
dcramer                    554 (0.6%)
Dan Wendlandt              472 (0.5%)
atul jha                   431 (0.5%)
EmilienM                   428 (0.5%)
Joe Topjian                411 (0.4%)
Eric Windisch              376 (0.4%)
Ed Kern                    341 (0.4%)

At the OpenStack Summit last week I started looking for data that will help us shape the scope for the documentation for the coming release. With the right scope, we can keep up with code. Right now the docs scope that DOES release with code is docs for Python developers only, at docs.openstack.org/developers. However it seems people want install docs more than anything around release time. We will release the docs next week, 4/30/13, and have basic install docs in review now. We’ll need to keep track of doc bugs once we release of course. What we want to do in addition to decreasing scope is to increase resources, so we are working with member companies to create and fill upstream OpenStack documentation positions at each member company. Other creative ideas are welcome of course. I find this creative resourcing fascinating and I’m not about to whine about keeping up. Rather, I want to keep rising to the challenge.

community techpubs tools work writing

How It’s Made: the OpenStack API Reference Page

Glad you asked! The site at http://api.openstack.org is a collection of HTML pages, and one page has an especially interesting story about how it is built. The http://api.openstack.org/api-ref.html page provides a listing of all the API calls for all OpenStack APIs that contribute docs to the page. Currently the only API that is still a work in progress is the Networking API, but here’s a patch in review and they soon will be included also.

The page has a lot of Javascript and CSS, DocBook and XSLT, XML and JSON behind it, which enables a few cool features. One is the details button, which gives an expanded set of information after you click it. Another cool feature is the ability to display either XML or JSON examples for the request or response with a drop-down list, and you can choose which to show by default. I also like the in-page search, which is more powerful than just using the browser’s page search feature because it digs deeper into the descriptions, expands to show any hits on your keywords in required and optional parameters, and in the response and requests codes. It highlights the found terms after expanding. Another cool aspect of the page is that all the Compute API samples are tested against a gate using code in the nova repository. Tested samples have been added in meticulously by Laura Alves, an awesome doc intern, with additional thanks to Sean Dague and his cohorts poking nova developers during the last dev cycle to ensure we have test samples for all API calls.

I believe there’s a lot of value in a long listing of reference information for the OpenStack APIs, and I’m glad Joe Heck took the initiative to get a blueprint going for it. David Cramer, Joe Savak, and Thu Doan at Rackspace took the blueprint and made it a reality with the Maven plugin at clouddocs-maven-plugin. The original goal of the page was to provide an all-in-one listing of all the API calls you could make against OpenStack services. At the time there were 3 or 4 services. Now we could potentially have 9 services with both admin-level API calls and end-user API calls, not to mention the extensions across 3 or 4 of the 9 services. So we are revisiting the all-in-one design of the page. Another aspect of the page is that it’s the only place to get documentation for the Compute extensions right now and the only site with tested examples without spelunking the code itself.

So, how’s it made? The basic building blocks of the page are:

  • WADL files – Web Application Description Language, a proposed Wc3 standard in XML used for describing REST APIs, read all about it in the specification at http://www.w3.org/Submission/wadl/. Here’s an example with the Image API 1.0 WADL.
  • XML files – Sample requests and expected responses. For Compute, these are copied right from the repository and each code submission that has an API piece must contian templates that build the example. Here’s a sample file: userdata-post-req.xml.
  • JSON files – Sample requests and expected responses. Here’s a sample file: userdata-post-req.json.
  • DocBook file – DocBook is an established documentation XML standard. Here it’s used as overarching XML organizing file, you can see it at api-ref.xml.

With these building blocks assembled in the openstack/api-site repository, you must also have a pom.xml to make the Maven plugin build the resulting api-ref.html page. The pom.xml is called by a Jenkins job maintained in the openstack-infra/config repository in a .yaml file. To build it yourself locally, install Maven and then do:

git clone git://github.com/openstack/api-site.git
cd api-site/api-ref
mvn clean generate-sources

Wait a while (maybe even 15 minutes first run) for the build to get all the dependencies it needs, then when you see BUILD SUCCESS, open the api-ref.html file in the target/dockbkx/html/ directory and revel in all the features listed above. If you want to submit a change, use the Gerrit workflow all the OpenStack projects use.

The backlog of bugs for this page is maintained at http://bugs.launchpad.net/openstack-api-site. If you see a mistake or want to ask for a addition, feel free to log a bug there. Laura Alves, our GNOME Outreach Program for Women intern, did an excellent job this past three months maintaining the page. My fellow Racker Diane Fleming is currently doing doc bug triage and fixing for the page as well. Future plans include adding a navigation layer on top of the page so it’s not one long page, but lets you pick the API for the service you’re interested in. With the additional APIs and new versions, we definitely want to keep updating the design as the APIs themselves grow and mature. Feel free to join in the API fun.

api-refhtml page