Monthly Archives: December 2009

Language and socializing online

Lionbridge (a translation and localization firm), is conducting a survey to learn which social networking sites people around the world use the most, whether they’re using them for business or personal use, and in which languages.

They’re trying to get as many people as possible, regardless of industry, organization type, geographic location, to complete the survey to learn more. Lionbridge localized the survey into 18 languages.

Feel free to forward these links to your global neighbors. The survey will take a maximum of 5 minutes to complete. Responses are kept confidential. Only people directly involved with this project will have access to the individual surveys and data collected.

You can receive a summary of the results by providing an email address at the end of the survey.

Survey Link:

Hone writing skills or specialize?

Never permit a dichotomy to rule your life, a dichotomy in which you hate what you do so you can have pleasure in your spare time. Look for a situation in which your work will give you as much happiness as your spare time.
Pablo Picasso

Someone pointed out a bit of a dichotomy in technical communication the other day. It was such an interesting observation that I’ve been thinking about it for a while. The dichotomy is between the power of plain old writing skills and the power of “sexier” specialized skills.

What are the specialties?

Directions for tech comm that  Tom Johnson and Alan Porter discuss on their respective blogs is a movement towards videos and screencasting (screencasts category on Tom’s blog) or graphics and illustrating (comics category on Alan’s blog). Mostly the posts talk about how users don’t read the manual (which is apparently okay). Perhaps specialization is a wise direction to take, because it’s a specialty that won’t be taken over by “the crowd” as easily as writing., for example, was seeded with 20 professionally-produced how-to videos, and the community can add videos to the site as well. You can mostly detect which were made by professional film-makers, so it would appear they’re employable longer.

Content farms go moo

Since anyone can write, and content farms are impacting the web, filling it to the brim with quickly written, search-engine baited fast-food content, hone more specialized skills in order to thrive in the shifting sands of the web, right? However, content experts like Brian Massey say that all content, no matter the source, is what’s driving the successful websites and web applications today. The written word is still effective with measurable results, and is overwhelmingly more prevalent on the web today, page for page., for example, is a wonderful redistributor and aggregator of banking and investment accounts, a specialized type of content. Mint also creates content, such as the weekly summary newsletter, that encourages you to return to the site. This content is text and numbers, with lovely graphs, but it’s really the numbers that shine.

To summarize

With both sides pointed out to me now, I’m leaning towards the broader content strategy movement. I will help people get content from any source, even if it’s built by a community or (gasp) ordinary users. But I do see the value in video and especially in non-text-heavy mobile content as we roll into the new year and a new decade.

Here’s my observation. If it’s true that, the link shortener that’s popular on social sharing sites, has counted over a billion click-throughs per month, then it’s possible that social sharing will overtake search engine optimized content. As noted in 5 Trends That Will Shape Small Business in 2010, “Social search has the ability to eclipse the value of traditional SEO efforts.” A comment counters with the trend to go from text to video, saying clients should “record, record, and then record some more.”

Let me repeat that. Eventually there could be more people reading and clicking through links on social sites than searching and clicking through links in search results. How will that shift change how you create content, and how will you strategically choose the content that you create?

Focused communities

Community purposes vary as widely as the people who comprise a community. You know that participants on Twitter Moms are not the same people as those hanging out on Dad Labs community, instinctively. But what are some of the factors that differentiate communities?

Types of communities

As I learn more about open source communities, support communities, and documentation communities, I’m finding that people who talk about community in the enterprise use categories for the types of communities that exist: business to business is B2B, business to consumer is B2C, and customer to customer (or consumer) is C2C. Besides the audience and membership targets, what are some other factors that differentiate these communities from each other?


Does 90-9-1 hold true for B2B communities? Apparently, no. The participation inequality ratios are even more, well, inequal in a B2B community. Here are notes from a Twitter chat on the site, as recorded by Shara Karasic @sharakarasic. “Mike Rowland doubts the community manager’s myth of 90-9-1 participation ratio. In B2B space, blog metrics have a ratio closer to 99-.9-.1. In support communities where people can ask a quick question, the 9% expands.”

Focused communities

I also heard an interview with Gartner’s Adam Sarner where he addresses the question, “What if it’s drill bits, not “cool,” products that generate lots of buzz and conversation between consumers?” I’ve often wondered as a technical writer, knowing that not many of us work on products that would generate “fan” feelings, whether “fandom” indicates whether its worthwhile to pursue community or social interaction techniques. Apparently, focused communities can generate just as much excitement and connections, whether it’s drill bits or accounting tools.

Trip-ups for communities in categories

I think one basic flaw in categorizing communities is that talking about who talks to whom makes you think of community like it’s a publishing channel, which is not a good analogy. Whether you’re publishing reviews or complaints or questions or answers, the type of community matters a lot because of the changes in audience and author. But, not all the work of a community has to do with content production, and a community is not a “channel.” Connections, building trust, communication, and maintenance of all of the system are other tasks within a community.

In summary, I appreciate the desire to strictly focus a community. I’m learning more about how those communities operate, and it looks like lots of good people are doing the same. Feel free to point to more research in the comments, and I’ll continue to share my findings.

Content strategy and web writing

contentstrategyforthewebBoy, it must be getting harder and harder to be a web writer. I’m reading Content Strategy for the Web, and the web writer job description is intimidating! The quote that stuck with me talks about the Web Writers Real Job: problem solvers who write well. I do hope this quote describes many technical communicators today.

“The web writer’s mission? Useful, usable content that’s also enjoyable. It’s her job to begin a conversation with the reader that results in mutually beneficial outcomes all around. A problem solved. An article found. A connection made.”

All of these outcomes can be tied to thinking about technical documentation as a conversation starter. My book talks about social media enabling those conversations. Often, though, social distribution is simply the technique, but the web itself is the medium. When writing in that medium, we must be the best writers with the most considerations taken into account while writing. Search engine optimization. Style and voice when writing for the web versus print. Information architecture, organization, and label naming. Maintaining a content inventory. Auditing and editing content. Testing content. Handling workflow, reviews, and deadlines. The list could go on and on.

And here’s the thing. People are not backing down from figuring out a great web strategy despite the challenges, and finding great success. I had a great lunchtime conversation with Brian Massey, the Conversion Scientist. He basically mapped technical publications’ typical goals to the personas that help you encourage a conversion. Fascinating! He describes four personas typically used by marketing writers on the web in the blog post, Relate to Four, Connect with Thousands:

Methodical – Probably the first persona to come to mind when talking about traditional technical documentation, perhaps not even all that web-hungry. They want proof, answers, solutions, in an orderly fashion. They’d probably download and read a PDF file if it’s offered.

Competitive – They want information that will make them better, smarter, or cutting-edge. They may be the implementer at a company who will train others in the product you’re documenting, so they’d want scenarios that make them look good.

Humanist – To me, this type of persona, one who looks for relationships and the human element, might be difficult to deliver technical documentation to. They might pick up the phone to call tech support faster than looking up a question online, unless a community is behind the documentation that they can relate to. The humanist may also appreciate case studies that help them relate to a real story.

Spontaneous – They want to know the answer quickly and move on, so scannable headlines and topic authoring with any topic being a potential entry point will probably work well for them.

I’m definitely looking at my web writing in new ways. Not just in terms of deliverables, but also in terms of the content I can deliver to the right audiences, to help them meet their goals.

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.

FLOSS Manuals interview for the Puget Sound STC chapter newsletter

Robert Reynolds contacted me requesting an interview for the STC Puget Sound chapter newsletter. It was published in PDF form, Writing for Free/Libre Open Source Software, but with permission, I’m using it for a blog entry as well. Thanks again, Robert!

Writing for Free/Libre Open Source Software

By Robert Reynolds

When Tomas Krag needed a book on setting up wireless written in a short period of time, he compiled a list of smart friends, secured enough funding to buy a stack of plane tickets and also to pay friends of friends to vacate a London flat for everyone to squat in. Following a week of hashing out details, determining the writing scope, and developing an outline, everyone returned home with their writing assignments and within three months, the first edition was ready. That’s what’s known as a book sprint—the concept that Krag coinvented— when a bunch of smart people gather for a week to collaborate on a book. Also known as collaborative authoring, this concept has now been around for a few years.

The FLOSS acronym stands for Free/Libre and Open Source Software, so it refers to both free software and Open Source software (“Free Manuals for Free Software” is one of their mottos). In constructing the acronym, the Spanish word libre was included to emphasize the idea of liberty—the lack of boundaries—as opposed to the notion of something that is available free of cost. Through book sprints, FLOSS manuals and other high quality manuals are developed in a short amount of time, and the Web makes it possible for writers from all over the globe to get involved remotely, if not locally. I interviewed Anne Gentle about FLOSS, its usefulness, and its implications for the technical writing industry. She is a senior technical writer at Advanced Solutions International, which provides management software for professional and social organizations such as STC. She also authored a book (Conversation and Community: The Social Web for Documentation) and maintains a blog (

Robert: How did you get involved in FLOSS? was it an epiphany, or the result of open source work you did?

Anne: I heard about the need for writers for the One Laptop per Child project through Bill Gearhart who sent out a call to help to writers he knew, right before the first major release of the little XO laptop. I had worked for Bill at BMC Software and was intrigued about writing for open source projects, especially since I could see wikis were involved. As a parent to two sons under the age of five, I was immediately interested in the OLPC mission of bringing durable laptops to children around the world. FLOSS Manuals founder Adam Hyde approached SJ Klein, community content director for OLPC, at Wikimania in 2007 and that forged the relationship to document the XO laptop and Sugar education platform using FLOSS Manuals tools.

Robert: What are the long term implications from a technical writer’s perspective? What are the economic implications?

Anne: Open source success stories are everywhere, with Apache web server the quickest to come to mind and the easiest, most visible outcome for a lay person to grasp. Open source has so many projects with or without compelling stories though. Perhaps the software was built to fill a small need, and ordinary people may say “so what.” With either resulting uptake and popularity of a project, open source has introduced a new way of thinking about building software and along with the new ways of building software come new ways of thinking about content – either the content that usually ccompanies software or the content that fills a need at a particular point in time. From a technical writer’s perspective, the ideas of sharing content,
gathering a community with a common goal of creating content, and giving away content are brand new and somewhat intimidating at first. Those ideas are reinventing our careers as we know it. Writing in isolation contains less value for some projects. This value change represents the shift for technical writers – both in the short term and in the long term, I believe.

Economic payments are changing from monetary to payments of attention, links, reputation, belonging, and other measurements of value that don’t really have a dollar amount tied to them. By claiming this shift in payment will happen, I don’t mean that technical writer’s won’t be paid, but I do mean that a technical writer’s value will be measured in more than just dollars or in return on investment in business terms. Your reach and influence may be valuable. Your reputation may be valuable. These areas are implications that I explore in my book, Conversation and Community: The Social Web for Documentation.

Robert: What are the advantages of the FLOSS method, other than the quick production cycle?

Anne: The quick production cycle of a book sprint is the result of weeks of planning and perhaps because content already existed that can be improved upon or “curated” into a more helpful collection than it is today. However, that advantage is the direct result of longer investment in background work. Other advantages include the basic rewards that people pursue by being part of an online community – your content can carry a reputation through attribution, be shared more freely, and gain attention through the event of the book sprint itself.

Another good explanation of the advantages of open methods for documentation come from the FLOSS Manuals FAQ:

“when you use free/libre/open-source manuals, you have the right to use, modify and share the documentation freely. Manuals on the FLOSS Manuals site are no-cost to use online. For paper copies, we charge just for the paper and printing, and a little extra to support making more books. You can also take the online version as a PDF file and print it yourself. You can also edit the documents on the site, for example, if you find things are incorrect, out of date, or incomplete. (You can also change your own copy, but we appreciate if you help us
make the manuals on the site better.)”

Robert: What are the drawbacks? too many writing styles? Does an editor monitor/assimilate the work?

Anne: There would be drawbacks to writing content only through book sprints, and it is not easy to get quality content written with one voice during that one-week sprint. Often we’ll hire an editor for the week of the book sprint to help writers write better, organize better, and get the big picture. These editors are not the typical grammarian and style guide police types though. They are editors who can ask the tough questions and challenge the book sprint team to improve even when the going gets tough. Book sprints force decisions about documentation that may lead to conflict even during the week of a sprint. Collaborative authoring is not easy and some professional writers haven’t had to collaborate well in the workplace yet. A skilled editor and book sprint facilitator can arbitrate and help the team produce a higher quality book in the end.

Robert: What are typical contents and audiences of FLOSS manuals? Highly technical stuff for geek folks? Will it eventually evolve to more simpler content for lay audiences (like our parents)?

Anne: That’s a great question – before writing FLOSS Manuals book (or any set of content) it’s important to analyze the audience. One example of a book written to bring technical content to any audience is the book
titled, The GNU/Linux Command Line: An Introduction. There have been many books written about the command line, but one participant even said:

“I have written basic introductions to the command line in three different technical books on GNU/Linux and read dozens of others. FLOSS Manual’s “Introduction to the Command Line” is at least as clear, complete, and accurate as any I’ve read or written. But while there are countless correct reference works on the subject, FLOSS’s book speaks to an audience of absolute beginners more effectively, and is ultimately more useful, than any other I have seen.”

So the book projects themselves are carefully chosen and audience analysis occurs before a proposed book is even started. The only requirement to have a book created in the FLOSS Manuals system is that it is about free software. We try to write in a friendly, accessible style.

Robert: Can you talk about any future plans for FLOSS?

Anne: Currently the main project for FLOSS Manuals is to develop an open source software product for collaborative authoring and publishing called Booki. We are planning to work with on its development and it is in the very early stages of development. Using the lessons we’ve learned from our 14 book sprints to date, the platform would enable collaborative publishing as well as let anyone install and maintain their own installation. The FLOSS Manuals tool used today is a modified TWiki installation uses extensions that are given back to the TWiki community. It is all free software. However, it does require user support and the overall site may not be easily replicated. The Booki project starts from the beginning, developing the wiki and chat tools we’ve found useful.

Robert: Tell me more about the book sprints. Would this be a volunteer opportunity for STC members to gain more writing experience, network, etc.?

Anne: Absolutely. At DocTrain West last year, we had participants work on a Firefox manual and the chief engineer from Mozilla came to the event to participate. That book has been helpful to many people and that sprint also enabled 14 remote collaborators to make contributions within the timeframe of the sprint. Students, writers in other
countries, unemployed writers, you name it, all could benefit from participating in the FLOSS Manuals community. In-person networking occurs at the sprints themselves, which may be in all areas of the
world. Networking and connections can also happen on the FLOSS Manuals Discuss mailing list. Go to to sign up or read archives.

Robert: Have you ever been approached or would you (FLOSS) ever consider working with non-open source companies to produce manuals? (This would obviously go against the open source model…).

Anne: Companies have asked to use the FLOSS Manuals tool set for authoring, but the basic goal of FLOSS Manuals is to provide free content for
free software. If the software or project being documented doesn’t meet the criteria, a book isn’t set up in FLOSS Manuals. You could use any tool such as FrameMaker for shortened manual production. For example, IBM uses an in-person collaboration approach to authoring RedBooks. They bring together a team of subject matter experts for a short period of time to work on the outline and some of the content,
then they finish their “writing assignments” within a short time period such as 4-6 weeks.

Robert: Would you consider selling or licensing the FLOSS collaborative publishing platform to non-open source companies?

Anne: The Booki platform being built will be available through an open source license, in hopes to bring more collaborative publishing options to more documentation projects.

It’s an exciting time of growth for FLOSS Manuals – thanks for asking these great questions.

Writing for Free/Libre Open Source Software
By Robert Reynolds

Casting a wider net for content

I spoke with Rachel Potts, technical communications manager at Red Gate Software this week. They have done an innovative, seamless content combination for their Support Center ( to combine Author-it HTML output with technical support articles. Forums are one click away from those articles, and the authors include both technical writers and customer support pros. As she describes it herself, “The Red Gate support site is a help and support portal that comprises content such as product help, a knowledge base, marketing videos and public forums.”


I’m impressed and enjoyed speaking with Rachel about how they combined content from different sources. To integrate their output with the customer support articles, massive XML transforms are built against the Author-it output to populate the custom content management system that runs the support website. The content is not locked behind a support login, though.

Rachel has written an extensive article about their use of Google Analytics on the site, titled, What can web analytics do for technical communications? It’s a great article, one I’d been hoping for, that describes the useful metrics and what to glean from those data points, such as page views, unique page views, exit rate, and time on page. She also extensively analyzes search data. I also appreciated the section on identifying pages that no one reads. Fortunately, they don’t have that problem with their content.

She’s looking for examples of people who are pulling content from multiple authors in different areas in the company and also people outside of the company. Here are the three I sent her.

  • Adobe’s community help search is described on this page, and you can link to it to try it from there as well: It’s described as “This search index includes content such as product Help, language references, TechNotes, Developer Connection articles, and Design Center tutorials as well as the best online content from the Adobe community. Searchable content is chosen by experts at Adobe and in the design and developer communities, meaning you find the focused answers you need faster than with any standard web search.”
  • Sun Microsystems has projects where technical writers are gathering different types of content. NetBeans Ruby is the project I heard about at the STC Summit in 2008. Here’s their wiki: They post screencasts and tutorials to
  • Cisco has done some remodeling on their support community, for the better, by combining more content:

I’m interested in hearing your examples as well as talking to people who have cast a wider net to gather content for support sites. What are your favorite sites, either as a consumer or creator of support information?