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. 

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?

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.

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.

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?

A couple of observations:

• “Documentations” [sic] to me indicates an English-second-language speaker. Members listing that term as a skill is 245K, larger than the 107K “Technical Documentation”.
• Looks like it’s an easy popularity contest winner for “Technical Documentation” over “Technical Communication” with nearly 5 times as many LinkedIn members citing “Technical Documentation” as a Skill.
• Content strategy as a Skill listing is growing 16% year over year.

Fascinating snapshot. What do you think of this data capture at this point in time?

My request is that we have a branch of content strategy that centers on community.

1. Give us a specialty focus on building community through the expert and strategic use of content.

2. Produce analytical methods that look at requirements for each community persona using content for their goals.

3. Enable the community members to become content strategists themselves, creating, maintaining, and designing killer content in such a way that it grows the community and builds the community and accomplishes the goals the community sets forth.

What’s the business case for a position like this in your company? Let’s start with business case for content strategy:

• A repeatable process for content creation, publication, maintenance, governance, and careful deletion.
• Methods for tying content effectiveness to business goals.
• Measures for people who do this work, based on effectiveness of their techniques in practice.
• Disciplines to avoid regression and stop old bad habits.

What do I do if I want to call myself a community content strategist?

Let’s start with what I do. I have a pretty unique job here at Rackspace. I coordinate documentation efforts and stack content into meaningful bundles across multiple “core” projects that help organizations adopt OpenStack as consumers or deployers. I manage the documentation project just like a core code project including doc bugs, task tracking, build tool debugging, translation efforts, and all continuous integration aspects of keeping up with a fast-paced software project. I support the wiki, support developers sites that publish doc strings embedded with the code, customize the search engine, seek new content and new contributors, run a monthly doc meeting, participate in all in-person Design Summits held every six months, and ensure the vision for the docs aligns with the vision of the project. The vision is to increase adoption for OpenStack to help Rackspace meet its strategic goals along with HP, IBM, RedHat, and many other member organizations investing in open strategies. I’m creating a repeatable process, and trying to make methods and design tools for content effectiveness. I’ve been doing a lot of work and research into collaborative methods and need to blog about the findings to share.

Q: For starters, I was wondering what skills you have that you didn’t learn in schooling that helped you succeed in the professional world?

A: There are pretty specific web and server skills that I had to learn after finishing my education – mostly because they’re very fast-moving technology that I had not needed to try out during college and grad school. Every tech writer I’ve met has a different path into tech writing, but mine is a bit traditional. I got an undergraduate degree in Chemistry and spent a summer in a test lab, doing quality checks on infant formula. I found I was interested in the instrumentation manuals and how they were written, so in my final year of undergrad I started researching technical communication. As it turned out, there are graduate programs in tech comm so I went to Miami University in Ohio and got a degree. Part of the degree program was an internship, and I learned about online writing and HTML had just started to be a standard for the web. Since then, I’ve always worked in software documentation at large and small companies. I have had to pick up technology skills constantly along the way.

Q: How important was it for you to learn the technology before you started your job and what systems have you learned during your professional experience?

A: In my current job I learned much of the technology on the job because I hadn’t needed to know cloud computing prior to joining Rackspace. One attribute of technical writers in general is that we learn quickly. So in my case, it was more important that I could grasp concepts quickly rather than learn the technology prior to starting the job. I took this job about 2 months after the OpenStack project was launched, so really it would have been impossible to learn about
OpenStack, open source cloud computing, prior to starting. A clear understanding concepts and systems should be applicable no matter how the technology changes through the years (or months or days!).

Q: How often do you get feedback on the work that you do, and what form do you receive your feedback in? Who are the main people that you interact with (whether this be a team or SMEs, etc.)?

A: Getting feedback (and future direction) can be tricky in documentation because you want to write for certain users and audiences rather than for the team that wrote the product itself. I love it when I hear people say, “I no longer work for development. I work for the user.” They say it with disruption and evolution in their hearts and minds. They fully intend to serve the user the best they can, and user feedback is the most valuable type. I also believe in using web analytics to gather feedback on how effective your deliverables are.

Comments are a great way to get feedback immediately on a page you’ve written. Comments connect users to each other and to the authors of the content.

So in my case, I try to interact with community members and users as much as I do with developers who are subject matter experts.

Q: How important would you say knowing grammar and mechanics rules are?

Honestly, as quickly as the code moves, the documentation also has to move, so knowing grammar and getting mechanics right the first time are essential to having high-quality docs done quickly. I also review a lot of community contributions and need them to write English very well. I can serve as a grammatical editor during the review process but ideally the writer is very good at it already.

Q: Did networking play a large role in the job process for you and where you are today?

A: Absolutely – every job I’ve gotten has been a direct result of networking either through professional associations or through volunteer work on open source projects. I hold strong beliefs in networking being a constant activity – not for my own sake but for the good feelings I get from helping others, which I suppose is still self-centered.

Q: How much time did you have to devote outside of the work place to your job when you first started and now?

A: I love the flexibility that writing as a core skill in my career gives me – I can write from home, write at any hour, and the equipment I need is something I own and like to use already. I also love that I can attend user group meetings outside of regular work hours. I also get to attend twice-yearly in-person meetings with the community project contributors, which is just part of the job, not necessarily outside of the work place. I guess my answer is, the job doesn’t have an “inside” and “outside” of the workplace since it is so collaborative and community-oriented.

Q: And the ever famous questions, what struggles do you face with your job and what is the most rewarding aspect of it? Is the track that you’re on now, the one you planned to be on after school?

A: The struggle isn’t so much with the job itself but with the need to raise a family and have a home life when we’re so connected constantly. My daily  prioritization and focus is something I struggle with. This job is a dream job for me, though, it’s so rewarding to work in a community towards common goals. Plus Rackspace firmly believes in using your strengths to do work you love. I’m surrounded by really smart helpful people.

A graduate degree was my path to get to the awesome job I have now, but I don’t know that it has to be the “right” path. With the upsurge in open source documentation groups, it seems an apprenticeship in open source doc would still lead you to the right jobs and connections. After undergrad, I discovered technical writing, and had a very planned track through grad school to get to where I wanted to be. Even so, the career paths in technical writing in particular have a stodgy character to them sometimes. I’m more innovative and experimental with technical writing than the general group of technical writers subscribe to, and sometimes that causes twists and turns in the path.

Q: What is your title?

A: My business cards read “Content Stacker” which is a play on words – at Rackspace we are called Rackers and when you work on OpenStack we are called Stackers. So since I create, curate, source, and sort content for OpenStack, I call myself a Content Stacker. My title at Rackspace is Technical Writer.

Q: What piece of advice could you offer to students on being successful in the tech writing world?

Become as technical as possible while maintaining a user advocacy viewpoint. Be willing to experiment and definitely embrace the web and mobile devices as delivery mechanisms for information. Do what you love!

Next up was Warren Block, longtime FreeBSD contributor, Automating Documentation Proofreading

What tests of your doc can be automated? Many. He culled common misspellings from bug reports and his own knowledge. He used the AP style guide and wrote an algorithm from it. He found some word usages that usually need re-writing. Then he bundled it all up in a perl program called igor.

Writing Style Tests

you and your – look for too many uses
should – try to take out wishy-washy language if the user MUST do so
obviously and needless to say – can be offensive to many people, sounds like you’re talking down to the reader
starting too many sentences with “the”
e.g. and i.e. – nearly always used improperly with incorrect commas, also typically used backwards “for example” and “that is”
No examples – man pages require examples so you can flag on the lack of them

DocBook Tests

Rules different for different projects, but you could write the rules to put in a check for these.

• Whitespace
• Indentation
• Tag usage style
• Title capitalization – Uses AP Style Guide.

Program is called, igor, the lab assistant. Written in perl. Regular expressions all the way down. You can use the “ports” system:
/usr/ports/testproc/igor
or get it at:

http://www.wonkity.com/~wblock/igor

Usage: igor -R -y chapter.sgml | less -RS

On my Mac, which has perl 5.12 already installed, I downloaded the files from that directory, rename the igor file to igor.pl, and ran it against an OpenStack source file with this command:

perl -w igor.pl -R -y ~/src/openstack-manuals/doc/src/docbkx/openstack-compute-admin/computescheduler.xml

This is what I get in return:

computescheduler.xml style check:
"you" used 2 times
"your" used 3 times
"You" and "your" are informal and subjective.
Try to be formal and objective: "the file" rather than "your file".
"should" used 3 times
Use "should" sparingly, it is feeble.
Try to be imperative: "do this" rather than "you should do this".
"the following" used 2 times
If something is following, the reader can see it without being told.
"e.g." used 2 times
"E.g." (Latin "exempli gratia") means "for example" and is mostly
used in academic and scientific writing.  Consider replacing with the
more common English words.  Both forms are usually followed by a
comma for a verbal pause:  "e.g., a b c" or "for example, a b c"
"i.e." used 5 times
"I.e." (Latin "id est") means "that is" and is mostly used in academic
and scientific writing.  Consider replacing with the more common
English words.  Both forms are usually followed by a comma for
a verbal pause:  "i.e., a b c" or "that is, a b c"

I can take this set of “critiques” for this chapter, revise the chapter, and add quality and consistency! Pretty nifty.

Love this new cover, both photos are Creative Commons licensed once again. Let’s look between the covers though!

While thinking about the second edition and how three years had passed, I was pleasantly surprised that we could get to the three year mark with the book’s content remaining relevant and accurate. Seems nearly impossible on such a fast-moving topic as the social web. Yet while looking through the tools chapter to update it, we mostly tested URLs and looked at the categories. Surprise, nearly all example tools are still relevant and useful to technical documentation. Not all the exact examples still existed, but that was just interesting to revisit.

Next, I examined the book for three areas of improvement – organization, content updates and additions based on my most recent experiments and experiences with OpenStack at Rackspace.

Reorganization

With the tools being so much more a part of every  day life and work now, I have moved the “Concepts and Tools of the Social Web” chapter to become an appendix. It also lets readers go right into “Defining a Writer’s Role with the Social Web” where I walk through a strategic approach to the social web. I also moved an entire section about managing community methods into a new chapter titled “Analyzing and Measuring Web Techniques” to expand on the management practices and business value tie-ins.

Additions

Some of the best additions to the book are interviews with practitioners I’ve met over the years who are doing community-based documentation already. It’s a balanced mix of open source communities and corporations using community to add value to their offerings. These are scattered throughout the book. I answered these same questions as well about how my current work is structured.

Based on my observations with documentation comments over the last year and a half, I added plenty of commentary and guidance to “Commenting and Connecting with Users.” Selecting and implementing a commenting system is chockful of requirements and guardrails for comments included on every page of your documentation. I also give an example of how to process comments daily, weekly, and moderate comments.

I added some additional information to the wikis chapter based on my recent experience with a Google Summer of Code documentation summit, comparing and contrasting “typical” wiki writing to planned writing. Many wikis have become web content management systems that encourage collaboration, so while I continue to address wikis in a separate chapter, the community and conversation building remains at the heart of my book. For wiki-specific tactics using Confluence, I’d highly recommend Sarah Maddox’s book, Confluence, Tech Comm, Chocolate, which I reviewed previously.

I added a chapter about content strategy for community documentation. I’m definitely sensing a strategic specialty opening up right now, and want to keep exploring it through the lens of content strategy. There’s a great case study included as well about Autodesk and their learning communities. An interview with Victor Solano with Scot Abel lets you “explore how the software giant has leveraged the power of the crowd, software standards, and content management to meet the fast-changing needs of its customers.” I found it thought-provoking and inspiring.

If anyone would like a signed first edition, please let me know by sending an email to annegentle at justwriteclick dot com. We’ll work out shipping and payment (Paypal or check-in-the-mail) with the few remaining copies I have!

The terms social relevance, social networking, and social media, as a triad for explaining the social web became very clear to me after reading this rather complex title: Enterprise Social Technology: Helping organizations harness the power of Social Media Social Networking Social Relevance by Scott Klososky.

You see, these three social powers offer us content folks an entry to the strategic playing field of the social web.

What I realized is that there’s a stream of conversation and community throughout all these social threads. I hope that the second edition of my book connects these threads with more clarity than ever. I hope the long title doesn’t prevent you from tweeting about it. And I hope we all can relate our stories to each other to keep learning about the social web and growing our field’s influence on it. Let’s choose conversation and community as a strategic benefit to all our documentation efforts.