Engaging technical documentation isn’t written by Tina the Brittle Tech Writer. Who is she?

She’s the technical writer in Dilbert’s engineering department. Tina believes any conversation within hearing distance is intended as an insult to her profession and her gender. She strives to maintain her dignity while surrounded by engineers who don’t have a proper respect for her work.

Tina cares more about defensible positions on the engineering department than serving the customer. 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.

Of course, even the best laid plans can get thrown out the window in a tech writer’s daily work. But here are some ways to engage users with technical documentation. If you’re skeptical that these techniques are effective, go straight to the content analysis of user ratings. Helping 800,000 users in a year is an impressive number.

Go beyond text

People are drawn to images on a computer screen. The Community Roundtable has a great report available that you can glean many content best practices from. For example, the report indicates that “People seldom form relationships with text alone.” Boy, that’s true, and should compel us to incorporate pictures or a video.

I know, I know. Screen captures are a pain to take in the first place, and hard to maintain over time. Let’s think outside the box for a moment. Another way to incorporate images is to use artwork, however simple or stylistic. Take a look at this watercolor created by Oceana Rain Fields, a participant in this summer’s workshop at the Rural Design Collective web site. Illustration used under the CC Attribution 3.0 license (credited to Oceana Rain Fields with permission).

This image sticks with the readers of the manual, especially kids like the child-like figure shown. It should help the users identify with the manual (available online) and get cozy with it.

A friendly, helpful, and confident voice goes a long way in building a relationship in this asynchronous conversation. Screencasting, where you narrate while demonstrating a software feature, is one way to go beyond text in user assistance delivery. As an example, WordPress.tv offers screencasters and users a voice by enabling video uploads to their site. They pre-seeded the site with about 20 professionally-created videos, but after that, users were encouraged to upload videos.

Write informally

Michael Verdi, the content manager for support.mozilla.com (SUMO) has an excellent slide deck talking about Awesome Documentation where he describes some writing style choices they made recently to “Engage the Brain” including inserting humor or surprise and writing conversationally, such as “Can’t decide on just one page? No problem. Firefox lets you set a group of websites as your home page.”   Janet Swisher noted on the FLOSS Manuals discussion list that he also rewrote pages to not just answer what you can do, but why you’d want to do it.

Measure and adjust

Copywriters for campaigns know to do AB split testing – try out two brochures or two web pages on a sampling of people in the database. See which copy and design does best, then stick with that messaging until you see a drop off in use of the information. We don’t employ that technique often in technical communications, but as our copy becomes more web-enabled, I think we should start.

For example, some of the rewrites to pages on the support.mozilla.com (SUMO) site had measurable impact to the helpfulness of the page. For two of the rewritten pages, ratings were enabled. They could measure a 13% increase the number of people who clicked “Yes” for “Was this article helpful?” at the bottom of the How to set the home page article. Because of the high traffic on their site, that’s over 1,000 people per day. Given the number of people who view that page and the similarly-edited Profiles page, the two re-written pages were helpful to 800,000 more people per year. This demonstrates the power of web analytics, especially on high-traffic help sites! This example is fantastic.

Comment and be commented upon

I have many ideas for implementing comments in nearly any online help system in my article on the WritersUA site titled, Putting the User in User Assistance. Comments connect users to each other and to the authors of the content.

Enable storytelling

Your users have stories. Can you find them with some online searches to discover a hurdle they recently cleared or a snafu they’ve found? While case studies are typically under the purview of a marketing department, try to let users tell their stories, or find a way to showcase user stories periodically by linking to their blogs or tweets.

What other ideas do you have for engaging users with documentation? I’d love to hear more ideas.

Last spring I wrote up a blog entry pointing out some additional technical documentation wikis to add to a list I had in my “Wiki-fy Your Doc Set” presentation. A recent Twitter request asking for technical documentation wiki examples brings me back to both lists to try to compile an even longer, more updated list. These are in no particular order and the links were tested in August 2010. Other wikis are behind support logins but this list offers wikis that can be viewed without a login.

• All of the manuals on FLOSS Manuals site are authored and displayed in a customized Twiki wiki.
• Sun Microsystems (now Oracle) has many documentation wikis. The OpenDS Wiki offers a nice example. Also all the OpenOffice documentation is available on a wiki.
• Mozilla Developer Network
• Adobe Labs wiki
• Splunk product documentation
• Atlassian product documentation, specifically the Confluence documentation
• OpenCloud
• GigaSpaces
• Firefox Support Knowledgebase
• Second Life In fact, they single-source their embedded online help with the wiki as source.
• Ubuntu
• RightScale
• ExactTarget
• IBM developerWorks Wiki
• The MSDN Library from Microsoft offers many wiki-like features.
• Embarcadero RAD Studio wiki is actually 9 wikis, read the manager’s blog entry about it.
• WebWorks Documentation Wiki
• Tideway (now BMC Atrium Discovery) documentation

It’s no wonder I have to keep creating new lists. The examples are constantly changing. For example, the Facebook Developer wiki is being moved to another site.

Finally, if you are considering a wiki for technical documentation, I recommend reading my post, Hurdles and Hardships using Wikis for Documentation, reading Sarah Maddox’s blog, buying my book, and sharing your experiences with others. Here’s to enjoying the wiki journey.

I’m going into a listening phase for a client, where I observe their customers and partners habits online.

I thought I’d write up some of my techniques. The overarching task is listed as “Set up a monitoring system for “listening” to the social media participation by customers or partners.” The deliverable for this monitoring system is in the form of a report. But I’m also thinking of ways to set up a Google account so their technical writers can continue to monitor for months and years to come.

For starters, though, I’m going with who I know as much as what I know, picking the online brains of people who are close to this type of product. First, I searched through the archives of a blog of an industry analyst. I found a great post about a set of opposing videos the company had responded to when they were called out by a larger company (my client is the small company). What a find! Definitely set the tone for what they had recently gone through on the social web.

Next, I set up Google Alerts for the company name and two or three keyword phrases that relate to their products. I found a small group of blogs and bloggers dedicated to discussions about the technology behind the products, but not the product itself. There is also some standards work related to the product, which is good to know.

I also searched on LinkedIn for people’s profiles that have this company’s products listed. Then I made a list of their job titles. This client is already providing me with personas, which is great, but I want to add on more information if needed.

I searched on Indeed.com for jobs in high-tech metro areas where the job description contains some of the key skills the product requires as well as the product name itself. This search also reveals job titles.

I also set up a Twitter search that summarizes keywords and the company name, mimicking the Google Alerts. This search yielded more news and marketing information than I expected, which I could interpret as users aren’t on Twitter, but the companies are on Twitter.

Finally, I want to segment the customers by demographics, such as men in the U.S. aged 35-44, to see what their tendencies are for using online information based on the latest Groundswell Social Technographics ladder and data.

I’m also going to revisit the user assistance research that Scott Deloach put together, assembling best practices for user assistance.

Bug vacuums are a big hit in our house this month. I’m such the mom of boys, huh?

I like the bug vacuums because the bugs aren’t harmed and we can see them up close. Plus, it’s not a terribly loud activity. The bug vacuum hums and the boys just have bouts of mild shouting when they’ve found a cool-looking bug.

A great instruction booklet came with this particular toy. It’s compact, informative, pocket-sized, and I haven’t seen a better quick reference in my life. I immediately thought of Tom Johnson’s nice collection of quick reference layouts and links.

Here’s the first unfold, showing 10 essential field tips.

Unfolding the interior is a real treat – it expands to about eight times the size!

Sure, you could see this as primarily a marketing or sales piece, but only one side of the interior is attempting to sell similar toys – the rest has great instructions and ideas to “Get in the field!”

Anyone else have some “field observations” to share?

I haven’t done a round up of other places I’ve been writing lately, so I thought I’d offer a roundup of articles I’ve written for other sites.

What I’m writing

10 ways to motivate employees to use your CMS – Fierce Content Management

As a content strategist, what motivations help you meet your content goals when integrating a content system? Often the tool selection gets the most attention, yet the motivation of contributors is going to make or break the success of the project. Motivation is a psychological feature–a willingness to act that precedes behavior. You might think of a points system with rewards as a motivation system, but rewards are only one type of motivation. Read more

Putting the User in User Assistance – WritersUA

People on today’s social web are accustomed to participating in conversations, having a voice, giving opinions, offering reviews, and generally interacting with content and with each other like never before on the web. How can we enable users to respond to or contribute to user assistance? The answer could be a wiki, but a wiki is not required to enable more interaction with users. Here are some specific techniques, starting with the simple and moving towards the more complex, including wiki implementation practices. Read more

What I’m reading

I’m also posting reading items to my delicious.com/annegentle account that might interest my blog readers.

First Steps in Flex Screencasts

We meant to do that… (part I) | MsCyra’s Web Development Blog

How developers learn survey results – interesting

WDVL: ‘Users’ Versus People–Understanding What Motivates Online Behavior – Page 2

I did it! I passed and received my individual qualification (IQ) for Google Analytics. Hurray! And Whew!

The site offers a way to look up people who have passed their IQ test so you can verify if someone has it (here’s mine). I wouldn’t call myself an expert yet, since I think expertise comes with more and more experience. The test itself had well-worded questions, and you need 80% correct out of 70 questions.

I got 81% correct (hence, the whew). I double-checked all my answers, and if I didn’t know an answer for certain, I looked up information either in the Conversion University site or the Google Analytics help site.

With 90 minutes to take the test, my look-up-to-verify method would not have worked for all the questions, and I had to be quite familiar with the University lessons in order to verify what I needed quickly. I wish I could find out more about my incorrect answers. Apparently I need to work more on ecommerce, which makes sense since I’ve never run an ecommerce site so I don’t have hands-on experience with one.

Why pay for an individual qualification? Avinish Kaushik has an excellent post where he says for every $100 you invest in web analytics, you should spend $10 on tools and $90 on people with the brain power to think about the results from the tools. So for me, it made sense to test my brain power on a tool, but I realize that each site needs its own analyst behind it to choose the measurements and connect the site to the business.

A question about wikis and copyright came through my email inbox this week, and I thought I’d share it with my readers. It’s a good question and a common misconception of wikis is that all content is always liberated once it’s put on a wiki. Not so, and here is additional explanation.

Q: A colleague of mine is putting together a corporate wiki for engineers, researchers, and IT people and is concerned about wiki articles infringing on copyright for outside sources. For example, definitions of common terms, discussion of underlying concepts, etc. Is it sufficient if these items are reworded and paraphrased? If not, are citations required?

A: An excellent question. I think that people get a bit confused about the difference between protecting copyright and using licensed content correctly. I’m also surprised at how often people connect wikis to “content stealing.”

To pull from a blog post I wrote on the topic as a follow up question to my book, Choosing a License for Sharing Documentation Content,

“Copyright was intended to protect the creator from publishers publishing the content, “to the Ruin of them and their Families.” That ruination quote is pulled from the Statute of Anne, considered the origin of all copyright. Licensing the content is one of the things the copyright holder can do with the content to indicate how they, the creator, give permission for it to be used, sold, distributed, and so forth.”

To create a checklist for someone who needs to create, say, a glossary for IT-related definitions, you could use something like this list of questions:

1. Is the content you’re using as a starting point licensed? If so, what does the license allow in terms of reuse, redistribution, and so on?
2. If the license allows for attribution, have you attributed the content correctly? If there are other requirements for the license, can you meet those requirements?
3. If you still want to re-use the content but it appears to be licensed in a way that prevents that, you can either contact the copyright holder and ask permission to use the content or rewrite most of the content in such a way that it becomes your own. A “rewrite” for reuse stance is the least defensible and may have the weakest rationale for the content’s reuse, however.

A walk through on current content reuse on a wiki may be helpful. If you wanted to walk someone through an example, you could use Wikipedia’s image pages – each image has a rationale for its placement on Wikipedia. From their Help:About page – “Every image has a description page which indicates the license under which it is released or, if it is non-free, the rationale under which it is used.”

In the previous post, I talked about licensing your content so it can be used. In this post, I talk about using licensed content. I’m sure there are other, more complex angles for content and reuse. Feel free to discuss!

What are some pointers for developing a style guide for writing on the social web or for certain social mediums? I discuss style guidance at length in chapter 7 in my book, which is titled Finding Your Voice. In fact, I read from chapter 7 for my book reading at South By Southwest Interactive last week! Definitely finding my voice on the couch on stage.

If you’re working on a style guide for social media, you might find this collection of links that are all the footnotes from that chapter from my book, Conversation and Community: The Social Web for Documentation. All the references from that chapter are on delicous.com/annegentle/chapter7, but I think the most relevant are the ones I bookmarked very early on:

• A List Apart: Style Guide – Be concise, reader-centered, and seek clarity. One quotable line from it is “You need to get in, score, and get out.”
• Writing for the Social Media Everyman | Copyblogger – “The social media everyman is looking for an entertaining diversion, while being receptive to learning something new if presented in an “edutainment” format that ties the lesson into popular culture.”

I think the main points to remember when developing a style guide are to value highly clear, concise, to the point, honest, and attention-getting writing. Social media seekers read and scan quickly and the payment in the web economy is via links which translate to attention.

The Elements of Style turned 50 years old last year, and has sold 10 million copies. Nearly all our copywriting guidelines could be traced back to that original “little” book, an “attempt to cut the vast tangle of English rhetoric down to size and write its rules and principles on the head of a pin.” (Quote from an article in The New Yorker in 1957)

Web writing hasn’t changed the basics, rather, the web has increased style’s relevance to successful communication.

I’m late to write up my thoughts on Gordon Mclean’s post, Strange Bias, but I give him a belated thumbs up for great self-inspection and data query in the post.

My take? I read ““Why James Chartrand Wears Women’s Underpants” on Copyblogger in December. It’s a great survivor story that you should read in its entirety, but the gist of it is that James is a pen name for a woman freelance writer, who writes the popular blog Men with Pens. Merely representing herself as a man made a real difference in her career trajectory. I was shocked, though, that she never had to talk to clients on the phone and that she never went to conferences or spoke at conferences.

It made me wonder if I’d have 10 times the subscribers to my blog if I had started in 2005 as Tom Gentle. It really did. But we are who we are, and being genuine and transparent is all part of my blogging experience. Many of the opportunities I’ve had in the past 4-5 years are somehow related to my blog and the work ethic it requires to maintain.

And to answer Gordon’s question, “is it just me?” I’d say, my experience with tech pub teams I’ve been on are that men are the slightly minority gender. If you believe Quantcast web stats about the STC website, you see that 61% of site visitors are female. I’ve also observed more women at tech comm conferences than men.

But, socializing being, well, social, means you tend to relate to people like yourself, right? So followers, friends, and fans, being self-selecting as they are, may prove that men follow men and women follow women. I think Twitter certainly reflects this tendency, since research shows men follow men on Twitter. And bloggers use Twitter far more than the general population (See the pie chart on the Day 5 report).

If you read Technorati’s State of the Blogosphere you see that 2/3 rds of all bloggers are men. So the 55% blogs written by men that Gordon reads actually differs from the predictive 66% overall population. A great observation, Gordon, well done.

I finally did it, I wrote my first article for the Demand Studios content farm site, eHow. I wasn’t playing the part of a content farmer, though, but rather a farm worker, writing an article for little pay (compared to other rates I have earned as a professional writer).

I signed up for Demand Studios a few months back. There is a company called Pluck here in Austin that was acquired by Demand Media in the spring of 2008. What drew me to them in particular was not only the local connection, but also a fascination with turning search engine optimization on its ear. I first learned of these methods for content creation from this Wired article, The Answer Factory: Demand Media and the Fast, Disposable, and Profitable as Hell Media Model. Basically Demand Studios analyzes what phrases are searched for and then enter an article request in their database. There are currently 15,000 articles waiting to be written in their system. The pay for those articles is from $15 to $7.50 or less, and there are some assignments that offer profit sharing based on the numbers of views, apparently.

As a pro writer, I was dead set on following the style guide, knowing that attentiveness to the guidance given is part of the battle in producing good content. In their system, when I “Claimed” the article, it wasn’t immediately apparent which template I would be writing to, which made me a little nervous about attempting it in the first place. After clicking the article to claim it, though, I found that it was the About template. The guidelines were very clear – the About type required five sections with one-word section headers and the first section had to be titled Overview and contain about 75 words. The rest of the sections could contain more than 75 words but at least 50 words were necessary, and overall the article was targeted for 400-500 words. Quite structured.

The web-based authoring forms were easy to use, though it did not include a word count. I found it easier to get word counts in Textpad and then copy/paste the text into each section.

They’ve also very recently introduced an image library that you can search for images, the use of which is encouraged. You could add an image to each of the sections if you wanted. To my poorly trained eye, they seemed adequate but not too glossy, and none of my searches found quite the perfect image, but I included two anyway. They intend to allow people to upload their own photos, which I would have done in a heartbeat as I had one or two that would have been just right.

To my relief, the article I submitted by noon on a week day was approved by early morning the next week day.

It took me about 2.5 hours to write a 500 word article, I’m not proud to admit (or perhaps I should be proud of the quality that comes at that speed?) So my hourly rate for the article was right around $6.00 per hour. At least I didn’t have rewrites (she says sheepishly.)

To reflect back, I did the article because I wanted to see what the authoring system was like, and experience for myself the process of writing in such a system. To be sure, it’s easy to demonize such a system when you’re accustomed to higher pay for content creation. There’s a great interview on ReadWriteWeb by Jay Rosen, who talked with Demand Media founder and CEO Richard Rosenblatt, and it offers both sides of the issues surrounding content collection and the future of the web. I don’t want to take sides by sharing my experience. I just wanted to collect information based on the writer’s experience.

What do you think? Are content farms cluttering the web and driving down writer’s pay? Or is there an entrepreneurial opportunity here that offers a low barrier to entry for content creators any where to earn pay for  populating the web with content that’s already being searched for?