Wikis for Documentation?
Posted on November 28, 2007
Category Of Interest, Tools | 7 Comments
In catching up on my Blog reading, I came across this article Wikis For Documentation? Anne Gentle Provides Some Examples on The Content Wrangler site.
While I am certainly not an expert on Web 2.0 – what it is, what it’s good for – I have to admit that I am a bit of a hard sell on the value of Wikis for user documentation. I’ve been an internet user for a long time and have seen many examples of the precursors to “social computing†running off the rails. So are Wikis a good fit for documentation or not?
Anne has done a lot of thinking and researching into Wikis and has good ideas. (You should also take a look at Anne’s site – just write click.) It was fun to look through the samples and see how different organizations are using them. The Motorola Q Wiki
was very interesting, as it is basically a user guide online.
But I still have trouble seeing Wikis as being effective tools for delivering content. I can buy into the basic arguments of community contribution of content. You just need to make sure you have strong moderators to keep things on track and to deal with language, structure, and format issues. It’s the delivery side I have problems with. How usable is the Wiki for people who just want to find the answer to a question? Can you find content? For non-complex information like the user guide on the Moto Q Wiki, it seems like it might not be too bad. On the other hand, I have always had problems finding information on the MSDN site. In my opinion, I don’t think that Wikis have sufficient navigation and search capabilities to support large volume, complex content. But for simpler content, could be.
But you know where Wikis could be really, really useful? Audience analysis and usability. To create really effective content, you must know what your users really need. Everybody knows that. Take any technical writing course and “know your audience” will be drilled into you. But few writers really know their audience. To know your audience means you need to be able to anticipate all of the questions they go to your content to answer. Most writers have to guess about their users. Few writers get the opportunity to speak directly with users. Few get any sort of feedback at all. They are left to do their best. How useful would it be to be able to post your document on a Wiki and have users be able to comment topic-by-topic? To see the questions they ask? Very useful!!
Of course, the best solution might be a PDF user guide and a Wiki and a Help system providing a suite of content to suit many users and needs.
Multi-channel content. We can help with that!!
Comments
Find It
Subscribe to The Rockley Blog
-
Of Interest
Join us for Intelligent Content 2010
Join us at the Parker Palm Springs Hotel on February 25 - 26 for the second annual Intelligent Content Conference.
Intelligent content is content which is not limited to one purpose, technology or output. It's content that is structurally rich and semantically aware, and is therefore discoverable, reusable, reconfigurable and adaptable. It's content that helps you and your customers get the job done. It's content that is limited only by our imaginations.
Click here for more information about Intelligent Content.
New Rockley Group Publication - DITA 101
If you're in the process of implementing DITA, expect to do so in the future, or just want to learn more about it without having to wade through technical specifications, this is the book for you.
DITA 101 is designed for authors and managers. We've taken our years' of experience helping organizations to move to DITA and training our clients in creating DITA content and distilled it into an easy to read and understand format. Combined with our expertise in developing effective reuse strategies and adopting content management, this book covers everything you need to know to understand DITA from an authors or managers viewpoint.
Now available at Lulu.com! Click here to order!
Not sure? Want a peek inside? To get a copy of Chapter 3, Reuse: Today's best practice, click here.
Component Content Management Report 2009
The XML & Component Content Management Report 2009 is ready!
Now it it's second year, the report adds a new section on seven XML capable publishing tools. Newly updated to reflect the latest information, and based on extensive technology research and customer interviews, this groundbreaking report evaluates twelve major CCM suppliers and six prominent XML Editor tools.
The 360-plus page Report also documents industry best practices and identifies common pitfalls to avoid when selecting and implementing a CCM system.
This Report provides you with essential background to understand the CCM space and to make the best decision for your organization.
To purchase your copy, or to see a sample excerpt visit the Report page at CMSWatch.
Managing Enterprise Content: A Unified Content Strategy
"This book is destined to become the industry standard for implementing content management" Judith L. Glick-Smith, Amazon reviewer
-
About
The Rockley Group is a content management consultancy with an international reputation for developing effective customer-centric content management strategies.
This blog focuses on content component management; the tools and technology, best practices, structured content, information architecture, customer centric design and the user experience.
The entries are written by the Rockley Group consultants and invited guest bloggers.
Follow Ann Rockley on Twitter
We use Wikis extensively internally, and we are considering making a “Product Documentation” Wiki available externally soon. Our audience is largely our own staff though, the guys out at project sites, and whilst I can pick up the phone and talk to them, I think the Wiki will help us understand OUR audience a lot better.
That said, I think Wikis will continue to gather pace in this area. You mentioned not being able to find information? Well for a lot of technical people, GOOGLE is the answer to every question, so as long as you can search for it, it will be found.
Where Tech Writers come into play is properly cross-referencing and structure the information so that, once a user has found a topic, they can get what they want from it quickly and easily, or learn more relevant info if required.
It’s also fair to say that whilst most people have heard of Wikis, only a small percentage actually use them in anyway (this from a show of hands at my talk at TICAD conference this year). But I expect the numbers will grow.
[...] Wikis for Documentation? Steve Manning isn’t sure about using Wikis for Documentation but does think they could be a big hit in another, related area: Most writers have to guess about their users. Few writers get the opportunity to speak directly with users. Few get any sort of feedback at all. They are left to do their best. How useful would it be to be able to post your document on a Wiki and have users be able to comment topic-by-topic? To see the questions they ask? [...]
[...] appreciated Steve’s post “Wikis for Documentation” especially where he says that the delivery side is the weak point still. Agreed, but I have [...]
Hi Steve, I’m a technical writer of quite a few years experience, and now fairly new to the use of wikis for technical documentation. You’re absolutely right when you say that the finding of information is key.
I’ve used a number of documentation tools over the years, including help authoring tools with fairly sophisticated inbuilt tables of contents, indexes, keywords and browsing mechanisms.
Now I’m using a wiki to produce technical documentation, in the form of user and admin guides for some fairly technical products. We’ve found that the wiki does provide the tools you need — you just need to examine the wiki’s gadgets and think about how you can make them do what you want.
We’ve found some good plugins (addons) to produce a table of contents. Labels (or tags) on pages can generate an index. Our particular wiki (Confluence) has the concept of spaces – a kind of wiki within a wiki. This is useful for organising information, and it also allows us to confine the search to a subset of the pages when we want to.
Our wiki can also generate PDF, HTML and XML output of the wiki pages.
So yes, wikis are a bit clumsy
but, depending on what you need, they can do the job.
Hi there,
Great thread of discussion! I’ll be doing an article featuring this shortly.
I just finished a series on the Web 2.0 aspects of the MadCap Feedback Server which answers the closing paragraph question you pose:
…How useful would it be to be able to post your document on a Wiki and have users be able to comment topic-by-topic? To see the questions they ask? Very useful!!
http://charlesjeter.com/2007/10/04/
I’ve also been looking into corporate wikis, and appreciate your article. I’m still reserving judgement about how to define wikis for my clients, but as your post says, feedback is critical. The commenting on each topic is phenomenal and is the reason why that software impresses me so much.
– Charles
It seems to me that Wikidocs can only be effective if your users depend on the documentation to an extraordinary extent and your company puts significant budget into maintaining multiple two-way communication channels with the users. Otherwise, I just don’t see that there would be much participation. I’ve worked in several companies that used Wiki for internal documentation. In most of them, the project failed. Other, less participatory means of developing and disseminating docs were more effective.
Mike,
I’m willing to bet that in those companies where the project to use wiki for documentation failed, it had little to do with the wiki itself, and a lot to do with the organization’s culture. The thing is, wikis are so simple and easy to grasp, engaging to most people, and a better experience than trading word documents among a group, and trying to reconcile disparate edits. But for this to be successful, people have to be introduced to it, and shown these outcomes. If this doesn’t happen, or if the wiki project is started but people are allowed to just fall back into the familiar habit of email, then the wiki will fail.
Stewart