Scissor-style information slicing

A photo of old school remixing – printing out Wikipedia articles and recombining them.

This was a fun learning exercise as part of an IBM Extreme Blue student project creating a Sugar Activity called InfoSlicer.

Instead of using scissors, you can now slice information by downloading Wikipedia articles, editing and remixing them, and reading them online. also uploading edits to Wikipedia (Edited: woops, that was part of our use case and it should work in the future because it was designed with that extension in mind).

Under the covers it is using the Darwin Information Typing Architecture, also known as DITA (dih-tuh), a standard set of DTDs (or schemas) that allow sharing of open source transformations and an open toolkit implementation. See dita-ot.sourceforge.net for more information.

Watch a demo of the InfoSlicer Activity in action here:
http://ca.youtube.com/watch?v=Y0UDRi37MWM

This Activity was part of the Wikislice Project. We met our goal of creating custom curriculum materials from Wikipedia for OLPC but we still have work we want to do to help teachers use it.

I can hear all the librarians and teachers of the world saying together – cool!

This book was an easy, fun, read, and seemed especially pertinent after all the immersion into social networking I’ve been doing with SXSW Interactive. The 100-page book, Getting to First Base: A Social Media Marketing Playbook, is aimed at your company’s marketing department for them to read before deep-diving into the social media landscape. Julie Szabo and Darren Barefoot share their stories and even their somewhat embarrassing lessons learned, sparing you from the same fate while also encouraging you to start the conversation.

At talk.bmc our entire intent was to start the conversation. So I know how daunting and intimidating it can be, yet you also have to dive in and sit back and listen. It’s not an easy road to walk. But sometimes ROI stands for Risk of Inaction, so eventually you should learn your way around the tools of the trade. I still like Reach Or Influence for the ROI acronym when applied to blogging.

This book gives you specific examples of tools and technology you can use to start the conversation, and also has the proper amount of caution about being genuine and having good intentions. One of my favorite quotes:

The vast majority of products are
ordinary. Worse, most customers
have made their buying decisions
about staple purchases years ago,
and it’s difficult to change their
minds.

So, what to do? Pull off the “online equivalent of a publicity stunt,” create a meme. To me, this is such a daunting task I can’t imagine writing a book about how to do it. But sure enough, these two have the experience and case studies to show for it.

I also liked the “influencer” chapter, describing the rules for interaction with bloggers. Looking at it as a blogger rather than a marketer, it’s good insider information to have. For example, check out this trick! Let’s say someone has a feedburner feed, but they haven’t published that little graphic that shows how many subscribers they have. Just insert /~fc/ into their feedburner URL, and voila, you have the little graphic! Example: http://feeds.feedburner.com/~fc/JustWriteClick. Super secret way to check out your friend’s blogs and see if they have any subscribers to speak of.

Glory be, they like their technical writers as monitors!

Darren has a background as a technical writer, and when the book talks about who is a good candidate for the sometimes time-consuming task of monitoring the blogosphere, I’ll bet it’s Darren who’s giving the nod to the technical writer. My other favorite quote:

On the development side, technical support engineers
or technical writers are often a good choice. They’re good
communicators, tend to have a broad awareness of the
company’s products, and can even reply to basic
support-related posts.

I agree whole heartedly. I think the Agile technical writer that Sarah Maddox describes is precisely the right person to be identifying keywords, get RSS watch lists configured, and read, read, read, and respond when necessary or find someone in our company who can respond correctly.

Wikipedia doesn’t like marketers – tread carefully

And, my personal favorite topic, wikis, is addressed. The book has an excellent section about what to do and what not to do when it comes to the tricky waters of Wikipedia. To me, this section alone is worth the $29 for this book! Solid advice with the proper amount of respect for the community behind Wikipedia.

All in all, nicely done and a great read for marketers and bloggers alike.

A good friend of mine, Emily Kaplan, was kind enough to let me interview her via email to find out more about her experience with managing a wiki for technical documentation. She writes for the Motorola Q phone. Back in November of last year, just in time for holiday shoppers, the Motorola Q was on the cover of October’s Wired Magazine special issue (Wired Test). Here’s the article: http://wired.com/wired/archive/14.10/play.html?pg=14. Here’s a link to the Q wiki: http://www.motoqwiki.com/index.php?title=Motorola_Q_Wiki. An excellent starter reference page is found at http://www.motoqwiki.com/index.php?title=Motorola_Q_Wiki:About

Emily says “I’m a senior technical writer contracting with Motorola. My group has about six writers, an editor, and a graphic artist. We’re spread across state and national lines in Illinois, Florida, and the U.K. We write user’s guides for the high profile mobile phones that you see everywhere. (We have a sister group that produces the in-device help and videos.) I go to the office once a week and work from my house the rest the of the week in my pajamas.”

Here are the questions I asked her, along with the answers. I am trying to find out more about real experiences with wikis for technical documentation. The concept of wikis for technical documentation and user-created content was mentioned recently at the Writer’s User Assistance conference as the future of online help systems in the session “User Assistance Trends Panel: What’s Ripe, Hype, and Out-of-sight.” The panel consisted of Rob Houser, Dana Chisnell, Paul Mueller, Bernard Aschwanden, and Joe Welinske. By learning from others experiences, perhaps we can avoid pitfalls or craft best practices.

Anne: What types of information (concept, task, or reference) goes on the wiki, and did you pre-populate the wiki with certain basic information?

Emily: The foundation for the MOTO Q wiki was the user’s guide, which has mostly tasks and some reference types of info., such as diagrams of the keypad and how to insert a memory card, etc.

Anne: What are the main goals for the wiki – customer support, customers making connections on their own, community building, or using it as another way to publish information that customers can get elsewhere?

Emily: The main goal of the wiki was to provide customer support. Some users lose their manuals or don’t keep them or want to learn the latest details that might not be in their manuals if they have upgraded their software. Secondarily, customers can share information, which builds a sense of community. Not as much as a blog or user forum, but a little.

Anne: What type of maintenance do you perform on the wiki?

Emily: So far, I’ve had to do a product name change and also add new sections as new features have been developed. I do not touch any customer input, and we haven’t had to deal with malicious users.

Anne: Does wiki maintenance require more work on navigation or on content?

Emily: I haven’t touched navigation at all, only content.

Anne: Have you discovered a core group of users taking the wiki content under their wing?

Emily: We have two users who regularly add information for Verizon-flavored phones. Other user-based sites for this phone exist already, so they might be going there instead.

Anne: What feedback have you received from customers, if any?

Emily: I haven’t been involved with user feedback for the wiki.

Anne: Was there a customer request for a wiki or did the business decide to do this on their own?

Emily: One person in the marketing group spearheaded the idea. There wasn’t a customer request because it was a brand new product, but the type of product (a computer-like phone) suggested that the average user might be more web savvy than for other phones, so it was a natural thought progression.

Anne: What is the business justification for building the wiki?

Emily: It’s fast, cheap, and easy to maintain. And it reaches potentially millions of users. Like everyone else, we’re trying to reduce paper docs, and this is one attempt…

Anne: What underlying technology does the wiki use? MediaWiki? (That’s what it looks like to me, anyway.)

Emily: It is indeed MediaWiki. It also uses a SQL database in the backend for some user information.

And a bonus question/answer!

One of the downsides of the wiki that we haven’t been able to address yet is that we have many flavors of the MOTO Q phone coming out. These are phones that have totally different keypads and some unique features. We haven’t figured out how to reuse the info. or if we even want to create more wikis. (We’re talking 7 or 8 varieties right now.) Anyway, a dilemma…

At BMC, we do have user-generated content and are always looking for more ways to connect fellow BMC product experts. We have forums on BMC DevCon as one place for expert users to share advice, tips, tricks, and so forth with others. And, you can ask other users questions there, and our support staff chimes in as well. AR System has had an active developer community for years and the current site can be found at http://www.bmc.com/arsystem/dev_community/. TalkBMC is yet another place for us to connect with users, and give users the chance to let us know their experiences, and hopefully offer advice as well.

What do you think of wikis for technical documentation? Would you like contributing what you know? Let us know.

Inner gang? Mini empires? Am I talking about the online encyclopedia, Wikipedia? Why yes, yes I am. I’m reading “Who Writes Wikipedia” which is a study on how Wikipedia is edited and maintained. Is it really “a small group of colleagues working together toward a common goal?” A small group wrote that much content in about four years?

I’m interested in this subject because Wikipedia is a wonderful reference site full of content that usually is accurate and rings of authority even though it is maintained with an all-volunteer content creation and editing team. Seeing it and liking the results, I wonder how a wiki could be used in a similar fashion to build technical documentation sites that are user-built and maintained while offering the best, most thorough, most accurate technical information about a certain product or technical subject. Could we really get as valuable a reference for product doc by having a “small group of colleagues working together towards a common goal” — a goal of an excellent set of product documentation online?

Outsiders provide content, insiders clean it up

Come to find out, according to the article, over half of the edits are done by less than 1% of the users, about 500 people are considered to be the inner circle of editors, building consistency in wording and categories while fixing typos and editing content where needed to build more quality into each entry. The most active group of about 1400 people have done nearly three-quarters of all the edits. These statistics and claims are made by Jimbo Wales, the face of Wikipedia. Now, the article’s author, Aaron Swartz, tracks a few more nuances of this claim by studying random wikipedia entries, such as the one for Alan Alda. And here is his conclusion based on his study:

When you put it all together, the story become clear: an outsider makes one edit to add a chunk of information, then insiders make several edits tweaking and reformatting it. In addition, insiders rack up thousands of edits doing things like changing the name of a category across the entire site — the kind of thing only insiders deeply care about. As a result, insiders account for the vast majority of the edits. But it’s the outsiders who provide nearly all of the content.

Wiki for tech doc

Now, I’d like to try to translate this to what might work well for a wiki geared toward product documentation. You’d need a core set of very knowledgeable content providers, like a team of experienced users of the product. Those users would contribute a core body of knowledge to the wiki, and hopefully choose to first document the items that are either most popular tasks or the most-referenced information or the toughest concepts to grasp. Most likely that would be the subject matter they’d be most familiar with anyway.

But is there vandalism?

It also appears that my wiki graffiti concerns are likely unfounded… the article says, “A tiny handful — probably around 5 out of nearly 400 — were “vandalism”: confused or malicious people adding things that simply didn’t fit, followed by someone undoing their change. That’s such a small percentage, just over a tenth of a percent, that it seems for the most part there are few writers with malicious intent in their edits.

Real wiki writers tell their experiences

Reading through the comments, I also appreciated the “user experiences” from people who are actively editing Wikipedia content. One commenter notes that he “went crazy” adding content in areas where he had knowledge but found that once his knowledge limitations were surpassed or the well was dry, he went into a maintenance mode. With a “burst of new knowledge” he’d add more content to those areas but found those to be few and far between. I think that with product documentation a similar ebb and flow would occur — knowledge or experience with a relatively new feature would cause activity on certain articles but then maintenance would occur again.

How do you get enough contributors?

Probably the major limiter for a product documentation wiki that’s maintained by users is that the user base would have to be significantly large in order to draw enough content providers. If 500 people maintain Wikipedia, you’d probably need 50,000 users to get 500 committed people to provide content (or would you actually need half a million?).

How do you ensure consistency?

Wikipedia has a basic information model to follow that most people are familiar with, also — the encyclopedia and it’s article-like writing style and the content you expect to see in an encyclopedia is well known and the style is easily copied by any writer. Product reference would need some excellent modeling to follow, which is why I lurve the idea of a DITA wiki — structured content models that 500 people could follow consistently, writing concept topics, tasks, or reference topics on a regular basis.

I’m warming up to the wiki

We can learn a lot from Wikipedia’s success and I plan to continue to track their progress as it evolves and more policy is put in place. Perhaps the wiki has potential as a great product doc format.

What do you think as a writer? Would you be willing to write and maintain content for product doc in a wiki? What do you think as a product user? Would you want to read and would you trust the content provided by thousands of fellow product users? Maybe I should experiment by combining the two groups — user and writer — and start a FrameMaker wiki. Surely the FrameMaker user base just isn’t large enough to generate the content it would need to succeed. What do you think?

You can submit entries to Merriam-Webster’s Open Dictionary

In the spirit of Wikipedia (which by the way, isn’t as editable as it used to be), Merriam-Webster now has an Open Dictionary. So far there are over 2800 entries. You can submit an entry or browse submitted entries.

Okay, okay. I just wanted the last post of 2005 on talk.bmc.com. Happy new year, everyone!