Tag Archives: documentation

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.

Choose Conversation and Community

We’re closing in on the second edition of my book being released and available! I’m super excited about it. I can’t stop thinking about it. On the way back from the O’Reilly Open Source Convention, I started doodling in a new notebook when all “items with an on/off switch” had to be off, and came up with this diagram for what the social web means to me.

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.

Social Web

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.

techpubs wiki writing

Pick a beat for release notes

Journalists at Play Flickr: Lisa PadillaThis is fun. Fedora has “beat writers” which harken to journalists tracking a story. Each beat is a section in the release notes. I found it while poking around on the Fedora wiki pages that describe how they do documentation. See fedoraproject.org/wiki/Documentation_Beats.

I like this approach for a few reasons. One is that the term “beat” seems fresh. While I did have to look for the definition of “beat writer,” I had a notion in the back of my mind and it turned out to be correct. My initial reaction was, oh, it’s like a journalist chasing down a story, or beat reporting, being assigned to a regular route.

The second strength I see in this approach is that you can divide writing tasks and track progress. Having a “beat” assignment also matches knowledge areas to experts in that area.

Assigning someone to a “beat” also means they’ll try to uncover a story. More software documentation could use story telling. Try to tell the stories your users tell you – or better yet, let them tell their story. Curate these from blog entries or chase the story down yourself with interviews.

We’ve probably used this type of approach for ages in enterprise documentation, but this strikes me as a particular good way to parcel out work in a collaborative environment while still maintaining a high quality outcome.People are naturally drawn to their interests, and assigning them writing tasks based on areas of interest is a great method for making community documentation fun and engaging.

techpubs tools work writing

From Cement to Spandex – Making PDF and ePub

Which statement is true:

“PDFs are like cement.”


“Gentlemen prefer PDF.”

Turns out both are true! See my recent OpenStack blog entry, Hacking on Ebooks, for more context and attributions for those statements.

We recently held a hackathon which I blogged about earlier to discuss the prep work for creating epub from DocBook XML source for the OpenStack and Rackspace manuals. We had a very successful day of hacking on 11/11/11. A team of about seven writers, testers, and developers worked all day to try to make epub files. And sure enough, we did it!

Our list of bugs matches up with what others have noted about difficulties making ebooks, such as sizing images properly and enabling tables that scale when zooming in or out or being displayed on a small smartphone or a larger tablet screen. Turns out, many “pro” epub creators turn all the tables into images to avoid the sizing problem. We also noticed the problem with mobi output putting a new line for each list item, and I haven’t gotten the fix working yet. We’re starting with the OpenStack Starter Guide available as an epub download and automated outputting epub for that book. We’re checking out the downloads to see whether there’s interest and we’ll go from there!

techpubs wiki

Why Wiki?

In OpenStack-land, the wiki was chosen before I got here. It has a couple of flaws for my vision for open source documentation, which became more apparent when I recently outlined my reasoning for what content goes where. By walking through the “what goes where” talk about documentation and audience, I realized something about the system we have set up (and will tweak more) and it’s this: a wiki revisions a page at a time, but our doc system with comments revisions a site at a time, namely a release at a time. It’s an important distinction to make so that you decide what a web “page” contains. It’s important to be able to articulate your needs for a web page and how it’s updated so that you can tell authors how much information you need in a page.

A page at a time is really tough for ongoing maintenance, when you don’t choose correctly the amount of information in a page. There are also difficulties with the rather immature technology in many wikis. Wikis were designed for simple editing, fast publishing. What if you have a sweeping name change? Anyone doing tech comm in a wiki knows that’s a headache for many wiki systems. What about a final spell check? Page at a time. How about search and replace? Page at a time. And let’s not talk about the times when you have to add an entire column to a table in an ASCII-based wikitext way. Your wrists will revolt, I assure you.

But an interesting expectation for a wiki that wasn’t considered when choosing the wiki is the need for comments on each page. Right now the only web systems for OpenStack that enable comments on a page are the OpenStack blog and the docs site. The docs.openstack.org site is built with DocBook XML with Disqus comments embedded on each page. It’s not quite perfect, as we’re learning as we go that not everyone wants to moderate every comment from every book on the site, and we’re still learning how to turn off hundreds of comments at a time, but it’s a great solution to a specific need. Yes, even the comment system selection needs an information architect analysis before you begin, but that’s the topic of a future post.

Ironically, our wiki doesn’t have a way to comment. So we just use it for project documentation and any comments on a project design are actually done in person at a Design Summit, which is coming up next week. Even with the great opportunity for in-person interaction at the Summit, I get the feeling there are more people wanting to “talk back” and give feedback. And certainly people want to receive feedback, to a point where they specifically bring docs to me and request publishing through the docs.openstack.org system due to the commenting system.

So what this meandering post is coming around to stating is this: You don’t need a wiki to gather feedback on your docs. Find a way to embed comments on each page and a way for collaborators to edit and you’ve got two of the basic end-goals done.

Now, make sure the end goals are known in the first place. It’s possible you need a wiki because your information would be best written a page or an article at a time. This statement is obvious when looking through your hindsight lens but difficult to be disciplined enough to state in the first place. Answer the question “why” about five levels down and it’s likely you have a solution. It may or may not be a wiki, but it’s certain that if you’re producing web content, readers have certain expectations about the content when they come to it.

Social Support and Documentation Communities

Stories of Social Media Sticking in Unlikely Places
Saying, “No one reads the manual” just doesn’t hold water any more. Social technology has intersected even the classic user manual. There’s always someone who will read a book. But their true motivation may be a desire to become an expert on a forum or on Twitter, building an expert’s reputation or reciprocating assistance because they know they can rely on the social web to pay it forward.

The way to amplify knowledge is through social media, social networking, and social relevance tools, gathering a wider audience and working in an economy whose payment is in links and more links. To find a fix for a problem with a cell phone, some chose to go to the phone’s web site and download a manual. Others naturally search on YouTube for troubleshooting hints.

Social media for troubleshooting, training, or trying software or gadgets? Sure. Does this scenario sound familiar?

“The darn thing won’t sync up again,” she grumbled as she tried to unload the latest running data from a sensor in her shoe. The data should travel from the shoe to the iTunes software through her iPod which was connected to her computer so that the data would be uploaded to a third-party website. As you might guess, her first troubleshooting attempt started with the error message within iTunes itself, but after seeing a message from iTunes that told her to reboot the router, she instead opened up a browser window. Without even opening a new window, she searched on Google in a browser plugin. A helpful community posting from a year ago helped her get the data about her five mile run from her shoe to the website.

Google is a new entry point to every help system that is, well, helpful. From Google users can view videos, download PDF files of the manual, and read forum posts from people who have come across this problem before. Sometimes Google links go directly to a company’s set of manuals, but more often than not, Google is the entry point to user-generated or community-collected content from blogs, forums, or wikis.

Bloggers who build a reputation as an expert in Adobe products can now be found even more easily with the Community Help search tool, which is a curated collection of blogs, video tutorial sites, and other social media-centered sites. Searching within the Community Help on keywords such as “footnotes” offers up a list of links to Indesign experts who maintain blogs and offer how-to tips and advice.

If people are listening on Twitter to come to other user’s aid, even microblogging and instant messaging applies to the new aggregate troubleshooting guide. Social support communities crop up when social media tools are used to collect questions and answer them or point people on the social network to others who can answer their questions.

Documentation communities are built upon content systems such as wikis that lower the barrier to contribution by giving any page an Edit button. Rather than waiting for a long publishing process to finish, readers can be come authors and editors at the click of a button. And the publishing system itself notifies users when new content is brought on board.

Social and community techniques are a sensation everywhere, even for the boring, unsexy systems applied to customer support and technical documentation. You’ll be glad for it the next time your favorite portable gadget does an unfamiliar flip flop.

Trends and Open Source Writing

I get the greatest emails sometimes, thanks to my blog. Here’s the lead-in line that especially piqued my interest:

“I’m researching trends in technical communication for a grad-level writing class,”

She had me at trends in technical communication. And research. So of course, I read on.

” and I’ve found lots of posts on the web by established tech writers who specialize in the open source arena and who appear to be fairly entrenched in technical industries. Any references to the wanna-be writers in the same environment are followed by quips about their being poor, because they have to do a lot of jobs gratis to make a name for themselves.”

At the time I received this note, I had just started in my role as a technical writer and community doc coordinator for OpenStack, open source cloud computing software. I was surprised by the juxtaposition she noticed just in researching web posts, so I read on.

“Maybe I’m making the wrong inference, but it also seems that the comments about new writers are referring to grads who fit the traditional model of the 22 to 25-year-old coming right out of college. For my essay, I’d like to talk about the trends in Open Source where the “new” writer is middle-aged, possibly even retired, with years of expertise in a non-techie industry.”

Wow, I thought. A thesis about Open Source writers. I remember riding with Janet Swisher from Austin to Dallas for last year’s (2010) STC Summit, and we could count on both our hands the number of Open Source writers we know. This is a small group to study but a fascinating group in which to look for trends. Plus, I’m in a position to recruit writers who want to write for Open Source projects.

“Based on your experience, do you see an emerging need for writers (we’re talking paid gigs) who have lots of expertise in other areas, but are looking to switch to tech writing for their next career or as a part-time job in retirement? What avenues would be best to explore in the start-up phase?”

This thesis could help me understand this small group, so I responded and encouraged others to do so. But. I was left with trying to decide if I agree or disagree with her thesis, that Open Source attracts retired writers with years of expertise in a non-techie industry. I wanted to sift through which points I disagree with.

1. Age or years of experience in Open Source writers: The tech writers who are established in open source are often highly technical but not necessarily in a certain age group. I would say their technical skill set is the thing they have in common. I honestly haven’t met an early-20-something open source writer yet, come to think of it. I think you have a lot of work to do to “prove” yourself when coming to many open source projects as a volunteer. There’s a lot of meritocracy where only your work matters, not your methods necessarily. Here’s an example of what I’m talking about. Open source projects often use wikis (extremely lightweight CMSes) for documentation. Experienced, entrenched-in-the-enterprise writers are surprised at how effective a wiki can be for authoring and delivery, especially when they’re used to an Adobe toolkit. So, from where I sit, I don’t currently see “a trend in Open Source where the “new” writer is middle-aged, possibly even retired, with years of expertise in a non-techie industry.” Also, writers in open source nearly always come from technical industries.

2. Having to take lots of jobs gratis to build a reputation: Yes, you would have to do some jobs for free to make a name for yourself, but I’m doubtful that new tech writers have the experience needed to be a huge contributor or lone writer on an open source project. I say that because I have talked to college students (more than 10) about helping with FLOSS Manuals work or with OpenStack and I haven’t seen big contributions from any of them, yet. I’ve also invited college students to book sprints with little response. College graduates are another story, but I have no experience with recent grads to speak of, so I don’t have even anecdotal data to share.

3. Emerging needs for open source tech writers?: I definitely don’t see an emerging need for “new” writers looking to switch to tech writing or part-time in retirement to seek out an Open Source writing gig. That said, through FLOSS Manuals I have definitely met and worked with seasoned (but not retired) publishers and writers who have great contributions writing, testing, and publishing pages and pages of information. These weren’t paid gigs, although these volunteer opportunities certainly lead to great opportunities

These are just my observations in less than five years participating in open source communities. How have your observations differed?

Open Help Conference, Cincinnati, OH June 3-5, 2011If you’re interested in open source and documentation, please take a look at the upcoming Open Help Conference coming up June 3-5, 2011 in Cincinnati, Ohio. I’m the new kid on the block, embracing these techniques (maybe hugging them too hard?), looking forward to learning a lot and sharing my experiences. I hope you’ll join us!

techpubs tools

Open Help is Open

The tech writers who are established, recognized figures in open source you can probably count on your fingers and toes. About two years ago they gathered for the Writing Open Source conference, hosted by Emma Jane Hogbin. I couldn’t attend myself – it was the year of the pinata bat incident. But the group of people who were there are passionate about open source and documenting it. Shaun McCance, the GNOME doc team leader (fearless at that), has gathered a program committee of sorts to start a new conference, built on the energy and connectivity at Writing Open Source, called Open Help.

Open Help! I’m immersed in it daily now, coordinating OpenStack documentation. Open Help embraces all the people and systems that enable us to do amazing things with open source software. Open Help promotes open, transparent techniques for documentation and support, whether through community-based techniques, open source culture, corporate and enterprise settings. Open Help is both Open and Helpful! What more can we ask of our community documentation and support efforts than these two things? But how do you commit to openness and deliver on that promise? We all want to talk to each other about that and share experiences.

Scheduled for June 3 to 5, 2011, this conference will bring together the leads and supporting actors for successful open source projects. We will share ideas, best practices, success stories, and working systems that all of us can use to create and manage the best Open Help possible.

Open Help Conference, Cincinnati, OH June 3-5, 2011

Conference Format

Just like Open Help is not your parent’s help system, the Open Help Conference is not your parent’s conference. We want to encourage as much engagement and interaction as possible while still providing learning and sharing opportunities. How? By combining the best elements of traditional conferences, camps, and unconferences.

Conference Schedule

Held over a weekend, the intent is for people to pop in for as long as they can while also encouraging project sprints or retreats following the weekend.


We’re not simply inviting conference participants, we’re encouraging activators to join us in Cincinnati in June. As those who work as community members on open source projects can attest, you get more out of open source when you really connect with the vision for the project. We’re encouraging those who share a vision of better user experience, accurate and connected documentation, and top-notch responsive customer support to participate. Registration is now open for just $80, and will go up to $100 at the end of February.


This event’s success depends largely on participation and sponsorship, so we invite everyone to get involved in some way.

We want to encourage participation and interaction with our supporters. Ideally, a sponsor will send a group of people to participate. There’s real value in the connections and sharing that will happen in-person at the event. Contact me for more information about becoming a sponsor.

techpubs tools work

OpenStack Doc Sprinting

What a week! I’m recovered and finally able to reflect on our recent OpenStack Design Summit.

As you may have seen on the OpenStack Blog, we gave out three documentation awards to those who made a difference in the latest OpenStack release, Austin, by contributing documentation either on Etherpad or by submitting images or writing RST files for Sphinx output. Contributions have been super and steady and I’m extremely grateful for everyone making doc a priority.

We planned for a day and a half for a doc sprint as part of the Design Summit. In reality, I found myself being approached throughout the Summit by people who are interested in contributing documentation, writing doc in RST, or even pulling printouts from briefcases. The entire week exceeded my expectations.

On the third day of the four-day Design Summit, several of us gathered at a table in front of a projector to work on the documentation. During the week, some of the Anso Labs guys found me in the lounge and we talked about their all-new nova.openstack.org site which rolled out last week. Excellent! I matched up the theme so the swift.openstack.org site now matches. We discussed RST-based doc as the “voice of authority” documentation for developers. Basically, we were all advocating for “wiki or Etherpad as drafting area” and “rst in the source code as authoritative voice about the project” but are open to input on that.

Citrix contributors Zhixue Wu, Armando Migliaccio, and Youcef Laribi contributed an OpenStack Network Overview that we incorporated into the nova.openstack.org site along with a lot of implementation details from Anso Labs. The Citrix group also authored Rabbit documentation and Swift installation documentation which we’re folding into the sites now (and the sprint goes on…). Disney manager Joe Heck documented the entire Nova database schema with diagrams now available on the wiki. Remotely, David Pravec created diagrams showing Nova installation architectures and method and messaging calls which we’re able to incorporate into the site. All of us tested the installation documentation, and Bryan Walker from Accenture added edits for the single-node install based on his experiences. Once they were tested, Anthony Young took the wiki documentation and marked it up as RST to incorporate into the nova developer doc site. I also worked with Jorge Williams from Rackspace about the Rackspace API docs which he maintains in docbook, and Jorge gave me the source files for the Cloud Files API developer guide which we can re-use and incorporate into the OpenStack documentation. We also had a huge collaboration session with Dustin Kirkland and others to create specs for Stack on a Stick, a Live ISO image so you can get Nova running instances painlessly. I also met with Nati Ueno from NTT, who made a working VirtualBox image that runs Nova and we uploaded it to Rackspace’s CDN. Basically these give you Nova in a virtual system so you can painlessly run command to try it out, risk-free.

I hope I haven’t missed anyone – my apologies if I did! I’m finally recovered from the effort and able to look in the rear view mirror and wow, what a sense of pride I have in the OpenStack community.

This sprint felt like a great collaborative effort and gave me a chance to get to know the stackers who want to build great docs for OpenStack. While we didn’t do much future planning, I think we certainly got to know one another and now can comfortably email and comment on each other’s docs – that’s a huge step for anyone writing docs for any project. So I really appreciate all the hard work and want to say thanks for “gellin” through the sprint.

Agile Across the Enterprise

As a guest post on The Agile Executive blog, I was invited by Israel Gat to describe book sprints as an Agile method for documentation. Here is the beginning of the post and I encourage you to read the rest and comment on it there.

One of the Agile Manifesto’s basic balance equations is valuing working software over comprehensive documentation. This line of the Agile manifesto can be confusing to some supporting roles in an Agile development enterprise. As technical support staff, trainers, and content creators, what are we doing to fit into this Agile methodology, and what’s working well? Let’s explore some old habits that need to die, and some new rituals to fill that space.

Nowadays, Google’s search power offers software users access to documentation through forums, mailing lists, even through blogs and wikis maintained by the developers and authors themselves. These new conversational methods for documentation, support, and education have opened new opportunities for those groups to add value to software adoption. Ways to provide additional value to the working software include helping people learn the software, troubleshoot the software, or do their job with the software. Education, uptake, and support are all integral to the overall value of a software product.

Value proposition

First, a discussion on the value added by good websites, updated and relevant training materials, and a helpful support staff.  Those departments want to avoid the continual cost center perception. To do so, they find ways to add to the bottom line, such as:

  • increasing sales (enterprise) or increasing adoption (open source)
  • keeping users happy and satisfied
  • adding contributors to the community, whether helpful troubleshooters or prolific coders
  • decreasing support costs (in time and money)
  • converting participation into value
  • increasing positive perceptions of the software

In my experience, these values are universal to both enterprise software and open source software. Let me share my story.