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.
work writing

OpenStack Docs Boot Camp Wrap Up

We didn’t have to do pushups to get the wifi password, though I did consider that requirement for our boot camp theme and decided, no calisthenics required. We gathered about 20 writers and developers who wanted to learn about OpenStack documentation in the Mirantis training room for two days this week in Mountain View, California.

The idea for a docs boot camp came from the OpenStack Infrastructure team who held one back in June. We wanted to enable more people to contribute to OpenStack documentation through in-person training and team building. It’s not like a book sprint, with the goal of a book in five days, but rather a training session, with questions and answers in real time.

We even had a schedule! And presenters! With labs! We also held an unconference each day in the afternoon. As presentations sparked ideas for further discussion, we wrote them down on notes and everyone could vote on which ones to discuss further during unconference time.

Day one I gave an overview of OpenStack Documentation to give people the history and more context for how we follow development processes.

Jim Blair from the infrastructure team gave an overview of how doc builds work and how we can make templates for our doc build jobs. Since the openstack-manuals repo recently went through a restructure for simplicity (Sunday we were still merging!), this was very timely information. We ran through a lab to make a Jenkins job with a yaml file and also talked about our gating jobs and how to improve them to give better results in the content.

David Cramer, our Maven clouddocs-tools plugin maintainer, did a presentation about DocBook and the newly added support for
olinks
, a mechanism that allows for easier link management.

After lunch and a walk to a local park on the other side of a satellite Google office, we switched the schedule a bit to have Nick Chase tell us how to contribute to OpenStack documentation — by showing the onboarding process and how to commit a patch to openstack-manuals. We also had an unconference session about how to get new writers hired at different companies going with good projects.

Basically, read the OpenStack docs! Report doc bugs! Triage some doc bugs!  Edit based on our conventions and standards including proper spelling! Fix those pesky doc bugs! Get paid! Win!

CC-by-SA-3.0

CC-by-SA-3.0

Monday evening we enjoyed boating and dinner at Shoreline. Ahh. I also followed a Google self-driving car onto the Google and LinkedIn campuses! Fun.

CC-by-SA-3.0

CC-by-SA-3.0

Tuesday morning we were back at it, and I finally remembered to go around the room for introductions. We had doc-loving representatives and training enthusiasts from Cisco, HP, Mirantis, Nexus IS, OpenStack Foundation, Rackspace, RedHat, SwiftStack, and Yahoo!

Our next technical topic was a talk about API documentation with WADLs with Diane Fleming. I still marvel at the great output we can get from WADL, and especially appreciate how much work it takes to maintain accurate request and response samples. Diane has fixed literally over 100 doc bugs since she started working on OpenStack docs last year. She’s an amazing doc contributor.

Next we got all geeky about doc tools again with a presentation and demo of Publican from RedHat writer Stephen Gordon. I asked a ton of questions about their authoring processes, such as “do your writers write differently since they write “articles” instead of book “chapters?” Fascinating look into the world of all-open all the time. They are making the upstream OpenStack docs even better so their own customers get better docs.

Before lunch, Tom Fifield gave a presentation about the autodoc tool that is now working great for scraping the configuration options and putting them into the OpenStack documentation. It’s really amazing, we’re able to document over 1500 configuration options and keep up with code like never before. It’s still a manual, human-must-read process to make sure our groupings for configuration options are correct, but this autodoc tool is a really cool tool that we can keep iterating on.

After lunch, Shaun McCance talked about his plans for consolidating the Install Guides into a set of “choose your own adventure” style books. Michael Still and I had to attend the Technical Committee meeting so I had to miss out. The adventures are in an Etherpad and Shaun has six weeks to get this adventure done! Go go Shaun.

I think we all had a good time together, finding like-minded docs people, creating relationships with training-minded people, and solving some docs problems all in real-time. Thanks so much to Mirantis for hosting and feeding us so well, much appreciation to Rackspace for sending us and giving us such a fun adventure Monday and delicious Dish Dash Tuesday, and great gratitude to the OpenStack Foundation for supporting two travel grants and supporting fine folks like Tom Fifield, Stefano Maffulli, and Jim Blair. We can go forth and rock more docs!

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…

work writing

Openstack – The Terrible Threes?

I don’t know about you, but for my kids we suffered the terrible threes much more than any terrible twos. This week OpenStack, the open source cloud, turns three years old! Booyah!

Happy 3rd Birthday, OpenStack

From where I sit, I can envision some boundary testing as we define OpenStack for certain. And possibly OpenStack will ask “Why?” constantly? I think back fondly to the awesome toddler line of questioning, “But why?”

With my kids I invoked “house rules” quite often. House rule: no DSes or screens at the table. House rule: inside voices indoors and in the car. House rule: you can only point a squirt gun at a person with a swimsuit on. OpenStack has great house rules in our four values around open. These are house rules that I’ve felt we’ve embodied since the very beginning.

For the first birthday, I made this Lego still video for fun. I’m looking forward to more celebrations and I’ll be at the one in Austin this Thursday.

We automate all the things, while still making sure the people in the community get their say, get their code on, and keep working together.

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.

community tools work

PyLadies Austin OpenStack Presentation

The lovely and talented Barbara Shaurette invited me to speak to the PyLadies Austin chapter last night and I readily accepted! I was quite nervous as I had not one but two demos to run, one of which involved running actual Python code. I took Ed Leafe’s Pyrax tutorial and got it running with my Rackspace Cloud credentials, and poof, I can spin up cloud servers with Python!

Here’s the presentation, OpenStack How To – PyLadies ATX, with step-by-step how-to instructions for using OpenStack and making OpenStack. Feel free to point out any corrections and ask any questions here or on SlideShare. I want to keep improving my demos and presentations.

All the attendees got a card worth $100 credit towards Rackspace Cloud goodness, so I hope they use their newfound cloud power with gusto. Thanks Barbara and PyLadies Austin!

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

techpubs writing

Developers, Writers, and First Jobs

I constantly try to network locally with Austinites, and I’m meeting more tech writers with diverse backgrounds. One of Austin’s slogans is “Keep Austin Weird” and while our writers aren’t necessarily weird, their backgrounds can be!

For example, I know of one award-winning novelist in Austin who writes manuals during the day and novels at night. Did you know that Sara Gruen was a laid off Oracle tech writer who wrote “Water for Elephants” during a National Novel Writing Month? Those are cool stories of a writer’s path.

At a staff meeting a while ago, we went around the room and answered the question, “What was your first job?” I had de-tassled corn in northern Indiana when I was 14, getting it ready for hybrid fertilization by pulling the tops off of certain corn stalk rows. Another writer had worked a summer in a detention center, and another had been a bartender. Our diverse backgrounds all brought us to the same place and time and careers and meeting room.

Lately I’m seeing more and more need to hire programmers and coders who like to write and are excellent at it. This Microsoft Programming Writer I job has a great section in it:

You are comfortable creating both code and prose. You have a passion for the web and its ability to solve real world needs and create connections between people. You know that there are many technologies that fuel the web, and you’re like a kid in a candy store when you play with new APIs and discover how they expand your abilities. Your real satisfaction comes when you successfully teach someone else how to use those APIs, though, through a blog post or talking at a meetup. You’ve got a knack for coding: you use patterns and practices such as responsive design, you know your way around jQuery and Modernizr, but you prefer to code in adopted standards. In fact, you occasionally read W3C specifications for inspiration. Maybe you hope to someday edit specs…

This feels like the direction I’m moving in, and I hope you’ll come with me as I pick up blogging again. I’m interested in developers and becoming more and more like one. I’m not going after it like this “Don’t be a jerk: write documentation” post, though I do enjoy that style on others. My style is more about exploring, experimenting, trying things, and retrying.

How about you? What was your first job? Did you imagine you’d be in your here and now?