Monthly Archives: March 2010

techpubs tools wiki

Hurdles and Hardships using Wikis for Technical Documentation

After a Q&A on the Facebook discussion page for my book, Sarah Maddox and I had an additional email exchange talking about the difficulties people face when using wikis for documentation.

I believe that many wikis are in the range of “content management systems” or moving in that direction. But there are many difficulties in general with content management. Here are some areas I’ve heard from fellow technical writers:

Access control: Without being able to say who can view or edit what, some wikis are impossible to apply to tech doc due to serving specific business reasons with the content. A customer support article should not be subjected to multiple edits from wiki spammers.

Hierarchy: Without at least 2 levels of hierarchy, tech writers are stymied as to how to use a wiki without hierarchy. Of course. We have complex documentation sets to maintain and hierarchy is a natural way to organize topics.

Version control: The difficulty in maintaining or tracking several versions of a bunch of topics (or an entire namespace/space) to correlate with a software release version is frustrating to many – I’ve heard this is a basic problem for WordPress’s Codex.

Global search and replace – and don’t forget spell check: Writers are used to maintaining giant Framemaker docs where they could spell check and search and replace across large amounts of content. CMSes and wikis don’t make that so easy as before.

Search on the site itself: We’ve all become so spoiled by Google’s search algorithms that any local search engine usually comes up short.

Workflow: Wikis can be weak in workflow, even as simple as “approve or reject” a particular article.

Creating collections: More than just outputting to PDF, people want to single source from a wiki to create collections of articles based on tags, categories, labels, and so on.

Offline access: Many wikis think they’re the end destination for readers, but the classic scenario is “what do my readers do if they need to get on a plane?” One clever solution to this problem would be to offer the wiki on a USB stick – call it a wikiscicle.

Round tripping: Writers are always talking about roundtripping content. I’ve usually dismissed it as not worth the trouble – there wouldn’t be enough contributions that a team of writers couldn’t keep up with. I’ve finally heard a decent business case for doing so – from structured XML (DITA) contained in a CMS to wiki and back again. Translation (to 22 languages) and volume of edits or contributions are the key to this scenario.

One-click publishing (batch processing): On release day, you want to set all topics to released at once, but with many wikis, you have to go to each page one-at-a-time to click them over to the right state for release.

With plugins and advanced wiki engines, these hurdles are easily overcome. But Mediawiki, a popular wiki engine, flunks the first two tests that many technical writers would apply. These are the examples I’ve seen and some of what Sarah has experienced. How does it match up with your viewpoint?

Social media, conversation, and writing style

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, 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.

One community takeaway

Here’s a question and answer writeup that I have had squirreled away for a while.

Q: You recently published a book entitled “Conversation and Community“. If you could pick just one thing from your book about interacting with the community, what would it be?

A: I actually blame Whurley and Michael Cote’ for getting me interested in open source communities and wikis for documentation! And by “blame” I mean “thank.” 🙂 The one thing I’d take away from my book about community is how educational my experiences volunteering as a technical writer for open source projects have been. I feel like I’ve taken a wiki apprenticeship by volunteering with FLOSS Manuals, writing free documentation for free software. I got my wiki feet wet writing for the kids, parents, and teachers using the One Laptop per Child hardware and SugarLabs education platform.

I found that I was interacting with community members and volunteers through the wiki infrastructure itself. For example, we all know how difficult it can be to open the OLPC XO laptop when you first see it closed up. I used an “Art Wanted” wiki page to request simple line drawings showing the opening of the “rabbit ear” latches in a simple step-by-step fashion. In a few weeks’ time, I had links to two images sent to me through my wiki “talk” page from a volunteer that show the two step process for opening the laptop very clearly. This kind of story amazes technical writers who have been working in enterprise environments where a graphic design request wouldn’t have that fast turnaround time.

I also learned that early interactions with people can lead to bigger collaboration opportunities, and that sometimes in-person collaboration is the most efficient. My favorite community event from that experience was the week-long Book Sprint we held in Austin in August 2008. We invited all sorts of recognized community contributors including Walter Bender, one of the founders of the MIT Media Lab. He had written one of the first comments on the discussion for the original simple users guide in the OLPC wiki, pointing out some outdated screenshots. His involvement and helpful attitude led to enormously productive writing sessions at the Book Sprint. Embracing the wiki for authoring led to great results.

Respondents needed for user research authoring-tools

Today’s post is from four graduate students from communication and information sciences at Radboud University in the Netherlands.

If you work, or ever worked, with Author-it, RoboHelp, MadCap Flare or Help&Manual, we hope that you are willing to participate in user research. You can participate by responding to all answers in their anonymous online survey:

Goals for research

The aim of this study is to gain more insight in user-friendliness of functionalities and overall user experiences of the following authoring-tools Author-it, MadCap Flare, Doc-to-Help, Help&Manual or RoboHelp. This study will produce three deliverables:

  1. A scientific article
  2. Based on the results a matrix will be created, depicting for each authoring-tool a clear overview of its functionalities and its associated user friendliness score
  3. A more practical report with recommendations

In case you are interested in this survey’s results, the survey gives you the opportunity to leave your e-mail address. We will send you the results as soon as they are available.


Filling in the survey will take approximately 15 minutes. The survey consists of closed questions, two semi-open question and one open question, all asking about your opinion.

This research is conducted by four Master students from the faculty communication-and information sciences, Radboud University, the Netherlands.

Thank you in advance for participating in this survey!

Kind regards, Suzanne van den Berg, Nanette Hogervorst, Relus Kuijpers, Anne Rolsma

Content tidbits from a Community Roundtable report

Photo courtesy M i x y on Flickr using the CC By 2.0 licenseI’m reading (with vigor!) the The State of Community Management Report: Best Practices from Community Practitioners
from the Community Roundtable
, and finding so many wonderful tips about content from people who are community managers. I had to start a list of items that are relevant to technical communication and web writing to share. I naturally tend to target technical communications when I interpret the report, but this report is rife with content strategy.

I agree with this statement, and I think it means a positive impact on technical writers and web writers who are paid to create content by businesses.

The percentage of content that is desirable and
feasible to be formally produced versus community-generated
will have a big impact on resource and
budget planning. This aspect is likely to change – often
dramatically – over time, although it should not be
assumed that content should ever be exclusively

I personally haven’t found that completely community-generated documentation will serve most business goals. In the case of FLOSS Manuals, though, the community-generated content meets the main purpose of supporting and documenting  open source software. Still, hiring professional writers makes sense when you need to create content that meets very specific goals for a community, whether your goals are raising awareness, troubleshooting, or learning.

Now, this particular comment puts a bit of a stake in the heart of technical communication’s beloved single sourcing. I like the idea of associated content for technical writers to create. It’s branching into new media, such as audio or video, while still valuing the technical content that you work so hard to create. It’s not that one births the other, but rather the two types can compliment each other.

Instead of directly repurposing content from one format to another, create
associated content. For example, instead of turning a white paper into an
audio transcript, create a podcast discussion about it with the author.

Another line that causes me to press pause and ponder for a bit:

People seldom form relationships with text alone.

Instead, offer images, video, or music as part of the user experience in order to grow relationships. Fascinating.

And finally, the one that might be the toughest for professional writers, copy editors, and technical communicators to accept:

Learn to accept imperfection. Concentrate on making content interesting
and relevant rather than perfect. Imperfection actually allows community
members to better relate to it and engage with it.

And with striving towards imperfection as my excuse, I’ll close out this blog entry and encourage you to read the report for yourself, drawing your own arrows from the quiver and targeting what is important to you.

Google Analytics: Learning about Conversions at their University

I can’t help but admire the design of Google’s Conversion University for learning Google Analytics. They’ve built presentations with voiceovers that alternate between a male narrator and a female narrator. Most lessons are about 3 minutes to 7 minutes long, and I am learning as I go in a pace that I set.

For each lesson you can read what you’ll learn ahead of time, and after you click through to the video presentation, you get enough text explanations that both the visual/textual and auditory learner is well served.

I am taking these lessons to prepare for the Google Analytics Individual Qualification (IQ) test. It is a 90 minute test that costs $50 to take, and you earn an individual certification. You can either take the Analytics test or the AdWords test. And in true Google style, you can search for people who have gotten their certifications.

I got through First Steps the first evening, and nearly all the way through Interpreting Reports in another couple of hours. I agree that it helps to already be using Google Analytics so you can switch over to your reports immediately after viewing a lesson. You can also use what you learn immediately by applying it to your own questions about your site.

You can also view videos on YouTube that show examples, such as interpreting and acting on your data.

Wish me luck! You can read Frequently Asked Questions about Google Analytics IQ if you want to learn more.