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.

“Hoosier,” the somewhat odd name for a native from Indiana, may have its roots in conversation. One of the stories is that when a knock from someone at the door rang out, the person inside would ask, “Who’s here?” and the greeting was shortened to “Hoosier?” Since I grew up in northern Indiana, my memories of it are fond and nostalgic. I’m particularly pleased that some of the researchers of Twitter and conversation analysis are at Indiana University, a lovely campus that I visited more than a few times.

Is Twitter appropriate for conversation and collaboration?

Tonight I’m reading a paper titled “Beyond Microblogging: Conversation and Collaboration via Twitter” originally published in the proceedings for Hawai’i International Conference on System Sciences. Written by Indiana University professor Susan Herring and doctoral candidate Courtenay Honeycutt, it describes some research questions about Twitter being used for conversation and collaboration. To quote from their discussion, “This study investigated the conversationality of Twitter, with special attention to the role played by the @ sign.”

Specifically they studied the public timeline and the use of the @ symbol that Twitter users actually invented to talk to each other as described in this New York Times article, Twitter Serves Up Ideas from its Followers. The researchers also had to filter out the other uses of the symbol, some of which are entertaining. The emoticon @_@ is one googly-eyed guy that they didn’t intend for this study. The offhand reference to someone else using the @ symbol was also filtered out, along with email addresses, and location references such as “I’m @ the coffeeshop right now.” They wanted to study one Twitter user addressing another for specific reasons.

They found that the @ sign use has doubled in two year’s time, and that Japanese and Spanish speakers use it as often as English speakers.

How is the user-invented @ convention changing conversation-based content?

They also found, and this was interesting to me, that the use of the @ symbol may actually be expanding the types of content that are being used in microblogging.

We further found that tweets with @ exhibited a
wider range of content, in comparison to tweets without
@, and that most tweets without @ just answered
the Twitter site’s question: What are you doing? This
suggests that @, in addition to directly enabling a more
interactive use of Twitter, is indirectly contributing to
expanding the types of content expressed in tweets.

In the footnotes they further note the use of the @ symbol to address others is happening in Flickr, the photo sharing site, and I would add that it’s also used often in blog comments when responding to a specific person. It’s spreading as a standard, practically! Updated to add: right after publishing this post, I hopped over to Google Wave, and in a non-profit wave I joined, they had already implemented an automatic link to a person’s Twitter account if you addressed them starting with the @ symbol. Woah.

Learning more about conversation analysis

Last month I spoke with Tanya Rabourn, who is studying information science at the University of Texas who helped me begin to understand conversation analysis. She said that studying Twitter is “sexy” right now, but also pointed out that research in conversation analysis originated with studying suicide hotlines for conversation patterns. Yow. Conversations on IRC are also studied frequently – text based conversations are easily enumerated and analyzed, I suppose. There’s even a tool available for download from Indiana University called VisualDTA that helps with Dynamic Topic Analysis (DTA) by providing a way to visualize the structure of the topic flow within a conversation. (See pages 7 and 8 of the Beyond Microblogging: Conversation and Collaboration via Twitter PDF for examples of VisualDTA diagrams.) I also learned a lot by reading a blog entry that describes written discourse at Studying online conversation in the Twitter generation that Tanya had tagged on a social bookmarking site. I learned that Conversation Analysis studies the “norms and conventions that speakers use in interaction to establish communicative understandings.”

Customer support and Twitter

Naturally, seeing how I’ve written a book with Conversation in the title, I want to relate what I’m reading to what I’ve already written. (Or is that unnatural?) So, where are the customer support conversation analyses? Has anyone studied the back-and-forth written discourse that occurs in 140-characters to see what some best practices are for engagement and troubleshooting to help someone with Twitter? Or is Twitter simply a method to get to the front of the support queue by saying “Pay attention to me because I have a smart mobile device so I must have a bit more money than your average slob of a customer!”

I believe that phone conversations for customer support have been studied quite a bit – looking for phrases that sound like triggers for anger, avoiding long pauses, and when one party overtakes a phone conversation, it’s relatively easy to detect when that’s happening. But with Twitter, you could have long pauses intentionally as asynchronous, IM-like conversations happen when someone gets up from their desk and returns after a business meeting, for example. Neither party is angry about that long pause, it’s just an understood agreement in the Twitter medium that you may or may not be immediately responsive. How does that time factor change the “agreement” for a support exchange? Is Twitter reserved for the narcissistic whiners? Or are true relationships happening and caring, meaningful attention being paid to customers on Twitter?

Wait, don’t answer these questions. I want some data and dynamic topic analysis to back up your theory.

At FLOSS Manuals, we have been using a method called a Book Sprint -  collaborative authoring, one week at a time. In fact, Google’s “Summer  of Code” project has sponsored two of these sprints. The latest was  just this month for a completely open source video format called Ogg Theora. The sprint got a mention on slashdot last month.

The idea of a Book Sprint is that you can get lots of documentation written in a focused amount of time with the right team and some amount of content already in place. Gathering people in the same room when possible is extremely helpful and motivating as well. I like to think of it as using two wiki patterns – the Scaffold pattern first followed closely by the Barnraising pattern.

I often get questions about the viability and value of a book sprint in a corporate environment. Here are a couple of ideas for running a book sprint at a company.

Agile software development

In an Agile environment, the term “sprint” means a timeboxed iteration – a time period could be two weeks, or it could be three or four. You plan out the “sprint” based on the number of people you have and by correctly sizing the documentation goals for the sprint.

The term Book Sprint seems appropriate in an Agile environment. For example, plan the sprint to have the team focus entirely on doc for that iteration. That’s one company-type application.

Scenario-based documentation by Subject Matter Experts

Another company method of focused authoring that I know of is the one that IBM employs to write Red Books. A document coordinator brings in  the subject matter experts, they outline the RedBook in a day, then assign chapters to each Subject Matter Expert (SME). The SMEs usually go off and write for a while, then the RedBook comes back together with the document coordinator (I think this is accurate, but please do feel free to offer more detail by commenting).

Chris Almond gave a presentation at Central Texas DITA User Group meeting last year about using wikis for RedBook authoring – his slideshow is available on slideshare.net.

Writer’s luxury accomodations – seclusion and focus with collaboration

For Book Sprints, what we do is try to get a good group of people a great place to stay for a week and write. There’s at least 4-6 weeks  of pre-planning of the outline and possible content that already exists so that the sprint itself goes smoothly. Getting people to agree to audience and scope ahead of time is crucial. A book sprint  basically forces documentation decisions and priorities under pressure of one week’s time – so you want to get lots of questions out of the way before the actual sprint.

We also make them fun and offer food and “after hours” activities. The fun is crucial!

I just joined the Writer’s League of  Texas, and they actually charge people for writing retreats that sound  an awful lot like a book sprint, except that they’re not collaborative, they’re for solo writers to get writing done in a nice, supportive environment. It’s basically a nice location with some fun planned in as well.

We have case studies and lots of planning in a Book Sprint book hosted on FLOSS Manuals at http://en.flossmanuals.net/booksprints. Also,  the free sample chapter from my book talks about Book Sprints at length, see http://justwriteclick.com/book, and shows how much funding we needed for a book sprint last August that produced about 300 pages of printed PDFs and online HTML-based help.

I’m so pleased to tell you that my book is available now from Amazon.com and BarnesandNobles.com and for sale in Austin, Texas at BookWoman on North Lamar. Published by XML Press, this book was fun to write, difficult to finish, and a dream come true for me, a kid who read 500 books in a school year in the second grade. I love books and I love this book especially. But I do want to keep improving it with blog entries here and responses to honest and thorough reviews, even negative ones.

This sample chapter is available (by direct PDF download or on Scribd) to start the conversation and I invite you to comment here or on Scribd.
Free Chapter Conversation and Community

If you’re here in Austin, I’m working on scheduling some book signings at local bookstores, and be on the lookout for an invitation to a book release party in the next few months! I want to share my excitement.

And lastly, I have to thank my blog readers – you are collectively loyal, smart, funny, and engaging. I couldn’t have written this book without you.

According to this article in the Guardian, there’s a 5,000-word publication with the UK government’s guide to using Twitter. It’s available on scribd.com even, according to this Digital Engagement blog entry.

I think there are good lessons to be learned here that are relevant to any technical communicator’s use of Twitter to communicate with customers, users, or the audience we write manuals to.

At the STC Summit in May 2009, I attended Phylise Banner’s session about social media tools used in education, Learn what the Academics Already Know. Naturally, Twitter came up, and a writer who works for the CDC here in the U.S. pulled up their Twitter page. They had 9,000 followers. Yes, 9,000. My jaw dropped. Now, just two months later, they’ve passed the 10,000 follower number on the CDC_eHealth Twitter account. If sheer numbers are an indicator, these microblog posts and status updates are here to stay, and part of many communication department’s overall strategy for talking with real people.

The guidelines are summarized in the Guardian article, which I’ll excerpt here since they’re so well written.

Human: He warns that Twitter users can be hostile to the “over-use of automation” – such as RSS feeds – and to the regurgitation of press release headlines: “While corporate in message, the tone of our Twitter channel must therefore be informal spoken English, human-edited and for the most part written/paraphrased for the channel.”

Frequent: a minimum of two and maximum of 10 tweets per working day, with a minimum gap of 30 minutes between tweets to avoid flooding followers’ Twitter streams. (Not counting @replies or live coverage of a crisis/event.) Downing Street spends 20 minutes on its Twitter stream with two-three tweets a day plus a few replies, five-six tweets a day in total.

Timely: in keeping with the “zeitgeist” feel of Twitter, official tweets should be about issues of relevance today or events coming soon.

Credible: while tweets may occasionally be “fun”, their relationship to departmental objectives must be defensible.

I found all four of these guidelines matched my own experience with Twitter in the two years I’ve been using it personally. But as I look for ways to use it for my employer to connect to customers about the iMIS product and our documentation offerings, I have to pause a bit especially on the first one: Human and not over-using RSS feeds to automate tweets. I think that constant automation of tweets without an overall conversation and reaction strategy is a poor idea, but I do think that tips, release notes features like Confluence technical writer Sarah Maddox (Twitter as a medium for release notes) and others are experimenting with, have a place. I guess the key to execution here is to write microposts that sound like a real person talking about the feature and pointing to the release notes naturally. If you do decide to automate somewhat, be on the ready for replies, and ensure the timing is right and the frequency of tweets doesn’t exceed what your followers would expect.

The frequency of tweets matches the guidelines set by The Twitter Book (which I loved), at around two to four a day. In the case of people who would follow a technical writer or a software company’s account to find out tips for using the software, I would think a few tweets a week may be sufficient. I think that frequency and the timing of the Twitter posts go hand in hand. I’m contemplating Tweeting about a software release that went out a few months ago, though, so I should probably think again about that idea.

And finally, credibility is crucial for success when technical writers consider Tweeting. If the perception is that you’re tweeting in short bursts rather that delivering a technical manual or training video, well, then you’ve lost some credibility. Be sure that your goals with Twitter are in line with your goals as a technical communicator.

What do you think? Are these government guidelines transferrable to the technical communication world? Or are constituents different enough from software users that we’d better find somewhere else from which to draw guidelines?

Recently we had a few discussions on the FLOSS Manuals list about how to increase the quality of documentation for an open source project, and noted that quantity does not always increase quality. And someone noted that bad doc is worse than no doc at all! Naturally, I found parallels between the open source documentation world and the world of enterprise software.

Andy Oram started the discussion by sharing an essay positing that documentation will always be a cost, asking “Why is it more of a struggle for a project to provide information than to provide software?”  He asserts that any attempt to be comprehensive with documentation only results in overwhelming the budget, especially when video and in-person training are involved. I was reminded of Michael Hughes’ UX Matters post, Surviving Tough Times as a User Assistance Writer. He says, “We need to write less, and we need to write better stuff.”

Now, one counter question to Andy’s theory about bridging the training gap is this fact: training and education do not always come from manuals. So, in the case of an open source project’s documentation, does FLOSS Manuals align itself with the “support” mechanism of running software, or the “marketing/attention” mechanisms of getting software to be used?

In one case of a FLOSS Manuals user, Bill, he said he never can get people to read the documentation. He always ends up supporting people one-on-one with real-time communications. It sounds like Bill is the support department for his open source software project. Yet he could free up his own time by having killer doc that supports his users. I don’t think education necessarily aligns with “support,” though. Just because your users know how to use the software doesn’t mean they won’t run into the occasional bug or get stuck on a problem they can’t solve by themselves.

Here’s an example – I was talking to a guy who runs a WordPress consulting business with probably a dozen clients. He LOVES WordPress.tv because if a client has a problem, he points them directly to a link with a video that tells them what to do to solve their problem. He’s still the central support mechanism though. The difference is that he didn’t have to create the content that helps his clients.

I think that with the introduction of community and earlier feedback in our documentation, doc becomes more “fun” and rewarding. I have much more fun writing entries for my blog than I do for the everyday doc that I write for my day job. Part of the “fun” is that the blog gives me more feedback – comments from readers, and blog stats I can see every day that show me that people really are reading what I write, plus I can see what they searched for.

What is converging is the idea that all these sources of documentation – lists, FAQs, tutorials, wikis, and so on – could live in and be maintained by one “community” or even a single hired hand. I say it in my book, and I’ll say it again, we are living in an amazing time where the audience and user is more accessible than ever through these tools that amplify conversations and connections.

My coworker went to SXSW Interactive this year, and I merely went to lunch with people near SXSWi and followed the #sxswi Twitter stream, and now I am browsing through the sketchnotes. I went to BarCamp Austin on Saturday and presented about FLOSS Manuals and the Book Sprint methodology we’ve been experimenting with. It went great, and afterward I even got a nice compliment “You are a force of nature, aren’t you?” That made me grin big!

But back to Twitter for usability testing. How can that be done? The CMS Showdown featured at SXSW Interactive actually came up with a way to do it, and then there’s a video on Vimeo showing one of the participants watching and commenting as the Twitter stream goes by on her screen.

JoomlaSxSW AmyStephen’s Review of the Review from Amy Stephen on Vimeo.

Basically, set up a time for a certain number of website users to try certain tasks on your website or application. While they use the application, have them log on to Twitter and make comments, including a pre-set hashtag in their Tweets. By the end of the testing period, you’ll have a record of micro-comments (140 characters or less) collected with the search.twitter.com tool.

Somehow this use of Twitter to “judge” your product or documentation makes a lot of sense to me. You pick a hashtag and a span of time, and ask people on Twitter to read the doc or try the product at the same time, putting their thoughts up as 140-character or less Twitter posts.

Now, be sure to save off the stream of comments because, as Jenny Levine noted, the stream of the moment is momentary.

A week or so ago, people in the technical education sector did something similar to what I’m suggesting – they all discussed a topic at the same by putting the hashtag #educhat into their Tweets. We’ve been talking about a similar organized chat time for FLOSS Manuals.

I’ve blogged about uses for Twitter before – usability testing is just one more use to add  to the list.

I’m always on the lookout for examples of social media tools used to write and maintain online help. One trend I think I am seeing is the use of blogs as the basic release notes for new features in products, especially web applications. Examples are new Google Calendar features and SmugMug, where the entire blog is dedicated to Release Notes.

I’ve also found the Jing online help is written and maintained in Movable Type, a blogging tool. Many blogging tools can be used as content management systems, and it appears that Jing’s writers see blog engines that way too. There are lots of nice built-in features that they are taking advantage of – a nice Search field at the top of every page, and the Categories link at the bottom of each help topic give a nice collection of topics. There’s only one “table of contents” for the help system, and that’s the top page, but it works nicely as a site map. The overall effect is a very simple and elegant user assistance or support system. One detail I did discover while trying out the site, though, is that the MT search engine did not find hits for a search on “mpeg 4″ when the topic titled contained MPEG-4.

The use of a blog overall seems like a great idea for release notes – give your product some Google juice and search power as well as generate buzz for new features by giving other bloggers a well-understood infrastructure to link to you and give your entries trackbacks. If your release notes contain a lot of bug reporting or issue fixes, I’m not sure a blog is a good match since that’s not exactly a positive spin on your product release. Then again, sometimes transparency and honesty is the best policy. What do you all think?

Harjot Dhodi asked, “What is the difference in the role of: Document Architect, Template Designer, Writer, Technical Editor, and Production Editor? Can a person be told to handle all these roles?” I’ll try to examine these roles one at a time, and then answer the final question last.

Document Architect – Typically this person has a “big picture” view of the documentation and how to organize it to fit the user’s needs. This role involves organizing, dictating what topics will be written, structuring the overall deliverables (especially if there are multiple deliverables such as online help and printed documentation). I would say this role is for a more experienced person who has been with the company a while and knows the business needs for the documentation.

Template Designer – This person knows the documentation tools well enough so that they can maintain and design templates used over and over for consistent documentation while authoring so that the out put look and feel is the same over and over. For example, the role would involve designing FrameMaker templates for books and chapters and styles for the authors to use while writing.

Writer - This person creates the content. They should be familiar with using the templates and the style guide for the company.

Technical Editor – This person reviews the content and may also maintain the style guide. Some times the term “technical” in an editor role means they will check the documents for consistency with the product and technical accuracy throughout the document. Grammar and style rules checking is also part of the responsibilities of this role.

Production Editor – This phrase is less familiar to me. I would imagine that this person reviews output for any errors and does link checking for online deliverables. I suppose it really depends on what deliverables are produced. The Production Editor may need to check CDs to ensure the documentation deliverable operates correctly on the CD. There could be a lot of editing and testing and checking on certain production deliverables.

Can a person be told to handle all these roles ?

I think one experienced person could handle all these roles, and a single person could learn one role at a time and just keep adding each role to their abilities. In my company we do not have separate editors so we must review each other’s content. We all write content, we all edit content, and we have a document architect and production editor who is most familiar with the content and production tool.

Does this help answer questions about documentation roles? I’d love to hear feedback from my blog readers as well – what have I missed or what additional roles might there be placed upon one person?

I’ll be presenting Documentation as Conversation at the Austin STC meeting Tuesday October 7th.

Austin When

Tuesday October 7th
6:00 – 6:30 PM: Networking
6:30 – 7:30 PM: Program
7:45 – 9:00 PM: Networking dinner

Austin Where

UT Commons Center – Room 1.138 [Map]

Then in November I’m going to make the trip to the Houston STC Meeting Tuesday November 11th.

Documentation as Conversation: Working conversation and community into documentation using social technologies

Even if your documentation system does not converse with your users, your documentation can help customers talk to each other and make the connections that help them do their jobs well, play with technology at home, or learn something new in a classroom setting.

Instead of concentrating on single sourcing or the tools of the trade, this talk describes how you can think about documentation and user assistance in a conversational way, perhaps with the help of some social networking applications. I’ll also discuss the in-person FLOSS Manuals BookSprint as a use of a wiki paired with a community event to gather together writers to accomplish documentation goals for free, open source software projects.