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 pondering the 1998 article, Pages Must Live Forever (from Jakob Nielson’s Alertbox) while documenting the content aging report in MindTouch 2010 (Read the spec here, read the user guide here).

With redirects helping stave off link rot, it seems that we can fulfill the wish behind Kristina Halvorson’s plea not to allow the web become like the junk-filled planet in Wall-E. Instead of piling up old versions of pages, the links stay fresh while the content might age a bit, like a fine wine.

For help content, I can list reasons that older content might be just fine, no need to send off alarms.

• Software that has classic features that were well documented in the first place, those pages can be static.
• Pages that haven’t been updated but are still oft-visited I would consider to be fresh, not stale. As long as the comments don’t indicate a problem with the content, it can be considered fresh.
• Depending on how well it’s resourced or energetic it is, your writing staff and community can only add a finite amount of content per week (or month). So the percentage of old content may be higher than the percentage of new content. That ratio is probably okay as your site ages. The mark the report sets is two years (24 months), then the content might be “old.”
• Depending on the scope of the aging report, an older product would have older help pages. Filtering helps you tune in the grouping of pages where you might be concerned about stale pages.

Two years would be a long time in a web application’s life, but perhaps not so long for an enterprise application. As usual, the answer to “Must Help Pages Live Forever?” is “It depends.” The real question that I’m trying to answer is “When are Help Pages Stale?” I believe two years is a valid and reasonable line to draw. What do you think?

“Anne, I see you as an advocate for community documentation” – what a great compliment. I was so pleased with the response to my STC Summit talk last week, Strategies for the Social Web for Documentation. Here’s the short description of the talk:

Let’s say that the most driven and driving developer on your team, who also happens to be a popular blogger, comes to you and asks why your end-user documentation doesn’t allow comments or ratings. Rather than stammering something about Wikipedia’s latest scandal, or reaching for imperfect responses that sound like lame excuses, do your homework and learn best practices from others who are implementing social web content that is conversational or based on community goals. Along the way you may realize there are good reasons not to implement a social media strategy, based on studying the potential community and time you’d spend in arbitration with community members on contentious issues, or you may discover that you can borrow from benefits of a single approach while still meeting business goals.

Objectives:

1. Identify specific types of tools on the social web, such as tags, blogs, wikis.
2. List risk areas and pitfalls.
3. Identify writers’ roles with social media (instigator or enabler).
4. Plan a strategy of listening, participating, building and then offering a platform or community.

I’ve also posted the slides on Slideshare for all to see and share with others.

While talking to technical writers who are struggling to find the vocabulary to describe their new way of working in a content curator or community role, I got the sense that we’re all trying to reinvent our approach to traditional documentation. Coming together at a real-time, in-person event helped me focus my thinking and I appreciate all the dedication that went into the event.

If there ever could be a Cliff’s Notes for the wiki chapter of my book, I think I’m writing it now. I’ve been working on a great project with MindTouch. I visited them for a focus group with other technical communicators and technical support pros back in February in San Diego. We had open source community documentation represented, we had the health information industry represented, cloud computing, and high tech software writers, Agile writers, and document collaborators. It was a great time, discussing tips, tricks, and the trials of managing lots of content with specific purposes in mind such as learning, education, customer support, technical support, and internal collaboration. The write-up for how to run a focus group of this type is quite good – see Seek Omega: How to hold a Professional Focus Group that Produces Quantifiable Results.

After such a great session, we all continue to talk online thanks to one of the members setting up a LinkedIn Group, and MindTouch also invited us to work on a project to write up specifications for using wikis for technical documentation. We’re basically creating best practices using wikis for documentation, such as:

• templates, such as DITA’s concept/task/reference as well as FAQ and solution guidance through multiple tasks
• tags for workflow, assigning tasks, editing, and categorizing pages
• content collection and curation
• reports that assist with content curation and community documentation

I’ve been circling back with the members of the focus group while I write these specs, and working with Steve Bjorg, the CTO for MindTouch. His attitude towards development is,  create something with a sense of openess and collaborate with users as early as you can. It’s a refreshing way to make software. He describes these first go-rounds as the “Cliff’s Notes” for creating technical documentation with wikis. It’s not as robust as other solutions yet, but it sure does have features that are exciting glimpses at the future of documentation. I’ll post more in the coming weeks and months as we round out the features.

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!

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?

I’ve published a long-ish article on the WritersUA site where I describe techniques for user assistance that let the user participate. It starts with simple techniques such as comments and moves towards community documentation efforts. Please read and share Putting the User in User Assistance. I’d love to hear what you think about these techniques.

While doing some research for LugIron, a startup here in Austin where I serve in an advisory role, I found a slideshow discussing signs of successful community launches by Joe Cothrel, a VP of service at Lithium.

Now, what they mean by “community” is a larger than 5,000 person audience, enterprise-type (B2B or B2C focused communities), and containing primarily forums and blogs (followed by everything else.) So, it’s not quite the same as the wiki communities that I’ve studied and participated in. But, what’s interesting to me is that one of his Warning signs on page 8 is a quote from the enterprise:

“We want to do a pilot.”

Huh? Really? Wanting to do a pilot is a warning sign of eminent failure? I guess with blogs and forums, you would want full dedication to the efforts and the goals of the community. But with wiki communities, I think a pilot is a great idea. Pilot content, pilot collaborators, pilot wiki.

What do you think? Do wikis fold up easier than forums? Are pilots getting a bad name in corporate-sponsored communities? Is this a case of the vendor wanting full dedication in their sales engagements?

I appreciated SocialText’s Ross Mayfield describing the various levels of interaction in his One on One interview with Fierce Content Management. The interview reminds me that social context alters behavior and motivations. Think of an intranet situation, where interactions are between bosses, colleagues, direct reports, and coworkers. The goals in this context are to increase productivity and collaboration speed, but corporate culture changes motivations. Then consider the context of an internet site, where interactions and customer relationships can be deepened and enhanced while providing customer service. Contributors to a wiki or any online content management system will certainly vary their behavior in accordance with the offline expectations of them.

I think it was in the book Groundswell that I read a case study where a company brought in a wiki, thinking that Generation Y employees would embrace it. But Generation Y wisely stayed away, because they didn’t have the authority required to make the system work well. Since the higher-ups stayed away from the new system, there was no leading by example, nor was there incentive for the newest, less tenured employees to use the system.

Patrick Davison is a digital artist living in NYC, and he designed the cover for my book. His Ignite talk has a similar theme – considering how your reasons for using a particular site or application (such as Second Life) shapes how you act there. The title is “The Plight of the Digital Chickens” and I think you’ll enjoy it as much as I do.

What are other examples of context shaping online behavior? I’m sure danah boyd has great examples in her papers.

Jakob Nielson and his research group, Nielsen Norman Group, have done it again – letting us know how users are actively perceiving and using social software for different business tasks. This research is important as the social web evolves so that we, as web content creators, know the best ways to present and offer different types of information, especially for corporate sites. He pulls it all together in an Alertbox from October 12, 2009 titled Streams, Walls, and Feeds: Distributing Content Through Social Networks and RSS.

What does this research mean for user assistance delivered through social means?

Voice matters – People wanted a specific voice for certain corporate brands. For example, the BBC was thought that it should have a more professional voice in its messages. But for other corporate brands, people wanted a more casual style, but the biggest reason for unfollowing a company rep on a social networking site was annoyance at the frequency of posting. My thinking? Don’t post your entire release notes links via Twitter in a week – instead spread them out to avoid drowning out the other people that your readers are also interacting with. I talk about finding your voice in chapter 7 of my book, and this research finding is certainly relevant.

Consider context – Updates that came through RSS rather than social networks such as Facebook, LinkedIn, and Twitter, were thought to be more “official” and trustworthy. However, readers have a lot more control over what they see – and readers who read the second page of a stream are nearly unheard of. They don’t seek out past postings. I have seen this happen on my blog here at JustWriteClick – once a post drops off that first page of about 10 posts, it’s only seen again when someone from a search engine looks for something very specific, such as the End-user Documentation in an Agile Environment post. What else is interesting about offering RSS feeds for information is that users’ habits haven’t changed in 3 years, though RSS use is on the rise and people are selective of the feeds they track.

Keep up – Twitter and Facebook are sites that are visited daily – can you keep up if you decide to engage customers there? And is there a place for end-user documentation on these sites? My take is that you shouldn’t start unless you’re willing to keep up. And in many cases, you probably don’t need to start on certain social network sites. If your group haa corporate goals like maintaining customer support by tying the social network interaction very tightly with your end-user documentation, then Twitter or LinkedIn may be a good match. Facebook may be a match also, depending on your message. Non profits, for example, find Facebook a great match for education, training, or raising awareness. If your corporate alignment as a technical writer is with the training and education department, you may find a niche case for using Facebook for promoting learning opportunites.

Make it useful - The most successful messages had substance, were timely, and met users expectations. Message usefulness scored the lowest of all the categories. Yikes. I would hope that as more content strategists and technical communicators apply their skillset to these messages, we can increase the utility.

Write well – Writing specifically for the medium is important to get the results you want. Probably the best way to write well for the medium is to read as much content as you can in the targeted medium. Apparently you can’t just repurpose content or use shortened text snippets that point to a longer one – users won’t click through.

Mobile findings

Only 4% of the users involved in the study sought out corporate messages from a mobile device. What I might infer from that finding is that mobile devices are for necessary in-field information, not for corporate messages syndicated through RSS or posted to social networks.

Email still fits

I found it interesting that email messages and newsletters may still be the best way to maintain customer relationships. Even though the user is responsible for deleting those messages, requiring more “work” than social networking sites, users still don’t browse through multiple messages from corporate “streams.”

Nielson’s summary says it so very succinctly that I can’t help but quote it directly:

Summary:
Users like the simplicity of messages that pass into oblivion over time, but were frequently frustrated by unscannable writing, overly frequent postings, and their inability to locate companies on social networks.