Articles in this Section

Wiki as a Document Deliverable

— Surag Ramachandran

Before we consider when to use and when not use a Wiki as documentation deliverable, let’s review some background information about Wikis.

We know that Wikis allow readers to easily update content. Wikipedia.org is one example that successfully presents technical documentation.

Wikis can be used:

• For collaboration–to make best use of collective information
• To manage dynamic content
• To record changes
• To alert users when new information is added using RSS feeds
• To cut costs on tools and upgrades
• To remove dependency on a software release cycle

Here are some of the approaches used by Web sources for Wikis:

• Wikipedia – Allows anyone to update information. Vandalizing may lead to ban/block of editing abilities.
• Schlorpedia – Like Wikipedia, but there is a curator to approve changes
• About.com – Does not allow editing. More like a blog where users can place their comments. Content responsibility rests on selected experts called Guides.
• Knol (from Google, about to come) – Follows a hybrid approach of updating information as well as leaving a comment.

Organizations can have an in-house Wiki to boost the efficiency by means of knowledge sharing and teamwork. If the organization has an Intranet then it can provide its users access to the Wiki. These users may browse incognito, but to participate they have to login. A Wiki server hosts many Wiki spaces. A Wiki space is a poised set of Web pages committed to a specific organization or project. Logged in users have the option of creating personal profiles. Profiles can hold information pertaining to projects, resumes, photographs, etc.

When to use Wikis?

One of the main advantages of a using Wikis is flexibility. It is simple to promptly add textual and image content, affix and categorize pages, insert hyperlinks, enclose documents, and do search. Any modification done by any user is instantaneously available to all valid users. With this flexibility, practical applications are only limited to one’s imagination. Wikis can be used for storage of:

• Technical documentation of a project

Wikis can be used as a central depository for project related documentation. Wikis can also contain: thought processes, justification for major decisions, interpretations and explanations about what worked and what did not, work products delivered at various project stages, to do lists, meeting minutes, and other supporting documents.

Looking in a broad perspective, Wikis can serve as more than a central depository. Wikis provide a prospect for: personal manifestation and documenting the wide framework of the decision making process. Wikis permit classification of content in a flexible linked manner instead of the rigid folder structure. This fastens the time to find required information.

Wikis can become the official record of the project with every required artifact structured and kept in one central location. Throughout the project, all team members can have access to this information leading to “all the great minds” on the same track.

Even after the project completion, related information is not lost and is available and structured for quick reference in the future. The information can also include pages like “lessons learnt” so that same mistakes are not repeated.

• Company infrastructure information
  

The information about the locality and infrastructure available in a company can be stored in Wikis. This information can include details of local conference rooms, network printers, links to regularly used business forms, building plans, and maps of emergency exits. This list may also include things beyond the company like address and telephone numbers of emergency contacts, local hotels and restaurants, directions to the airport, railway station, and so on.

• Information about the products and services

Wikis can contain high-level description of products, requirements management documents, customer needs, design process documentation, and best practices.

• Virtual collaboration details

The additional features offered by Wikis such as information blogs and threaded comments are ideal for virtual discussions, estimation of alternatives, and virtual decision-making. This information can be easily edited and modified by several people without loosing track of who added what and when.

When not to use Wikis?

Wikis are good in their own way, but are not “silver bullets” that can substitute and revolutionize all document deliverable methods. Here are some instances where a Wikis are not found to be ideal tools:

• Documents requiring automatic approval process are not Wiki candidates. Wikis control document approval by permitting edit permission to only a few people. After approving they have to upload the documents themselves. A workflow control process cannot be effectively done in Wikis.
• If a document needs to go through a formal review purpose, Wikis are not suited for going through the “formalities”.
• Wikis are not suited when documents are to be edited by different people. For example, if you are passing your user guide written in Word or Framemaker whose sections need to be technically edited by different subject matter experts, Wikis are not suited. The need to lock and unlock a document arises here and Wikis are not designed for that purpose.

Personal Experience

In my experience, Wikis were found to be suitable for putting FAQs, How To information, and Troubleshooting information where, regular and quick updating of content was needed. Wikis were also useful for storing technical information that was “buried” in emails earlier. Wikis enabled efficiently use, and reuse. In addition, compared to many other collaborative tools, learning curve for a new user was observed to be less in Wikis.

Going the Wiki Way

— Rahimunnisa

The ever-changing model of documentation makes one wonder about the best ways of reaching the target audience. Users want information that is accurate, readily available, and most importantly, reaches them on time. The mode of communication is not important. What is significant is the communication approach.

The concept of using Wikis to create technical notes and articles, dashboards, project plans, schedules, FAQs, troubleshooting tips, examples, customer best practices, cheat sheets et al is not unheard of. But delivering product documentation through Wikis is a fairly new avenue.

Wikis allow users to do what a traditional documentation does not–that is, make the documents dynamic by giving users the freedom to make the changes that they want to see.

The advantage of the Wiki approach is that it is flexible and quick. Wikis can be constantly updated with information rather than having to wait for revisions of the printed documentation. The subject matter experts and stakeholders from marketing, development, quality, , and also field-facing engineers can use Wikis to provide information or to correct the existing content.

Switching over to a Wiki way of delivering documentation requires some earnest thought-process. Once the decision to use Wikis is made, it is time to get started. Get a Wiki account, decide its purpose, define a basic Wiki page structure, create the content, and get the content reviewed. It is important to note here that the structure and content is never frozen. After all, one of the main purposes of a Wiki is flexibility.

To make a product-documentation Wiki effective, you have to structure the required information in easily readable chunks, keep the content up-to-date, and have easily navigable links to related information.

The Wiki approach is suited perfectly for open-source documentation where contributing and sharing information with the community is the key. It is an extension of collaborating with users who are willing to share their knowledge and contribute to the community. Another advantage of Wikis is that writers can save a lot of production time.

While Wiki-based documentation has its merits, it has its own set of limitations too. Some of the questions that have to be addressed include:

• What will be the ways of handling contributions from the internal and external users?
• How should the process of maintaining documentation for the sustaining releases of a product be dealt with?
• How can localization of the content be accommodated?

To conclude, Wiki-based documentation is not suited for all types of products. Each product has its own list of documentation needs. A thorough analysis of the requirements would tell us whether a Wiki-based method works well or not for the product. Make the right choice and go the Wiki way.

Rahimunnisa, a technical writer at Sun Microsystems, Bangalore, has more than eight years of technical writing experience. If you have any comments on this article, please send them to rahimunnisa@gmail.com.

I don't want to change!

— Manoj M. Kunju

Warding off the fear of being redundant even while welcoming Wikis

No two opinions about it. Human beings are inherently selfish, and most writers are human and by implication, selfish. And when the suggestion of exploring an alternative, non-traditional method of presenting documentation such as a Wiki comes from the top, bottom, or sides, they can’t help but think about themselves; how it’s going to affect them. Questions such as “Why?”, “What’s-all-this-fuzz-about-Wikis?”, and “What’s-wrong-with-what-we-do-right-now?” eventually evolve into concerns ranging from “Do-I-need-to-learn-and-adapt-more-than-I-am-prepared-to?” to “Will-I-still-have-a-job?” Some of these questions and concerns may be legitimate and should be answered by the powers that be. However, any fears that technical communicators have will become irrelevant because we consider using Wikis as not well-founded.

We’ll quickly discuss five reasons as to why even though Wikis may be a new territory for technical communicators, it’s not enemy territory, and certainly not filled with landmines.

1. What you know how to do isn’t going away: No one (I always generalize) who can spell W-i-k-i thinks that Wikis will replace every other method of documentation including the bulky PDFs and various online help systems we so love. Relax. Whether you like it or not, the bulky PDFs and the myriad help systems will not lose their relevance just because you start using Wikis to communicate with your customers. Wikis are most useful when they supplement traditional forms of documentation, not when they are the only sources of information.
   
   
2. Wiki-based product documentation doesn’t fit every product: Some fear that every product has to have its own Wiki site. No matter what your neighborhood Wiki-evangelist tells you, Wikis will not be a great boon for at least some products. Products that have a very specific application and a very focused (and small) customer base may not generate a lot of excitement with their Wikis. On the other hand, products that have a larger customer base and a more general application will have just the kind of information that a Wiki-based page can disseminate: tips and features, common issues and workarounds, best practices and timesavers.
   
   
3. Wikis are not as crazy as you thought: Many people are paranoid about Wikis being a breeding place for confusion and chaos. “Folks may come and introduce inaccuracy and substandard content out of error, playfulness, or even malicious intent.” Yawn! The truth is that it needn’t be so bad. With a proper mechanism for overseeing changes, you can prevent goof-ups that come due to oversight. You can also easily have different levels of users and contributors and classes of topics to keep the sacred and profane from mixing. Since changes to pages are tracked and can be audited automatically, Wikis have the power of being both flexible and authentic at the same time. And isn’t it chic that you can roll back any or all changes by just a few clicks that won’t cause your version control system to hang.
   
   
4. Wikis could even become your high-end functional specs: A thriving Wiki system could very well give you insight into every area that is important in building successful documentation: the customer’s skill and mindset, a list of tasks that are important to the user, features that are not documented clearly, and even tips and tricks that the developer may forget to mention to you. Such information is priceless (especially when it comes for free), isn’t it? Realistically, your Wiki page may not expand and enlarge in days or even months. Give it time. Always remember usability guru Jakob Nielsen’s advice on participation inequality: user participation follows the 90-9-1 rule:
   1. 90% of users are lurkers. They read or observe, but they don't contribute.
   2. 9% of users contribute from time to time.
   3. 1% of users participate a lot and account for most contributions.


5. You might even end up liking Wikis: Many writers who are exposed to the Wiki authoring model tend to prefer Wiki to the traditional file-based authoring model. This could be due to a variety of reasons, some of which are: the ease with which Wikis can be edited, the sense of accomplishment that comes from participative and collaborative authoring, the joy in actually receiving customer feedback and content, the accuracy and ‘current-ness’ of documentation. Some writing teams are pleasantly surprised when they receive positive reactions to their documentation when they release their Wikis. Maybe it’s just the wonder that a Wiki-page generates in a customer—“You mean I can edit it just by clicking here!?”

In these days of Web 2.0, Wikis provide an uncommon opportunity for the writer to embrace: an opportunity to be creative, collaborative, and considerate. Wikis won’t take your world by force. But if you allow it to, Wiki could be the tool that would allow you to change the world of technical communication. When was the last time you tried to find out what you wanted to know from some Website other than Wikipedia?

About the Author

Manoj M. Kunju is a technical writer based out of Hyderabad and works with Synopsys, the industry leader in Electronic Design Automation (EDA).

In addition to product writing, Manoj has dabbled with content writing and pre-sales writing. He also spent a few years as the PRO of a Kerala-based NGO. He can be contacted at manojmk@gmail.com.

STC India | Home | Contact Us

Copyright © 2008 India Chapter STC. All rights reserved.