Can wikis stand alone?

Anne Gentle asks, “Can wikis for documentation stand alone or do they need to be supplemented?”

Some of her points are these…

Top Reasons Why Wikis Will Increase in Popularity

I’m not an expert on wikis, but so far this is what I’ve noticed using the SharePoint 2007 wiki:

  1. Wikis are fast. This is literally what wiki means in Hawaiian. I think I can complete a documentation project in two-thirds the time using a wiki instead of a traditional help authoring tool.
  2. Wikis change the perception of help. Let’s face it: online help has a bad reputation of being useless. Wikis provide a new format that can counter that perception and empower critics with the responsibility to act on their jabs.
  3. Wikis draw upon collective intelligence. Even if you only have a handful of contributors to the wiki, drawing upon collective intelligence from actual product users is invaluable. Just getting one edit can expand the usefulness of your documentation tenfold.
  4. Wikis are convenient. With wikis, you don’t need to attach files to emails, compile an online help file, transfer folders to a shared server, decipher edits on paper, or try to interpret Word’s track changes. Editing of the files by SMEs and editors is a cinch.
  5. Wikis give the impression of being up to date. Even if they aren’t, wikis have more life. You can update them on the fly. One minor update to a page can renew the user’s faith that the documentation is current.
  6. Wikis have tremendous potential in the enterprise. Think about all the documents that project members collaborate on in the enterprise. Wikis will make project teams much more efficient (and fun).
  7. Wikis are a curiosity that merits experimentation. Everyone I meet is curious about wikis. They look at them with a new-found wonder. That’s worth something.

Internet resources for PostScript and GhostScript

Here’s an interesting page:

What is PostScript?   A page description programming language.   Mostly, it tells a printer where to place ink on paper. For most people, PostScript just silently works.   But you are not like most people.   You want more.   Here you go:

PostScript, GhostScript, drawing, printing, fonts, EPS, PDF, and more.
GhostScript gives you page images – it’s the EPS version of Adobe Reader.

More about wikis

To learn about the basics of wikis, see TechSoup’s article Exploring the World of Wikis

Tools for editing:

wikis generally let you edit the information on web pages in one of two ways. Some allow you to use a WYSIWYG editor like that in Microsoft Word, which allows you to click a button to make text bold or italics. With this type of editor, your view of the text while you’re editing is more or less the same look as what the all the readers will see. Without a WYSIWYG editor, you’ll instead need to use what’s called a markup language.

Which Wiki?

Well, I can’t say that I’ve spent significant time using more than a handful of wiki engines, but I’m familiar with MediaWiki , DokuWiki, PhpWiki, and Confluence . For my needs, Confluence is the clear winner—it’s got an extremely clean look, is absolutely packed with features, stores content in a database of your choosing, and has a dead-simple markup language. Confluence costs $1,200 for an installed version or $50/month if they host it, but non-profits can get it for free.

One thing the other three offer that Confluence does not, though, is open source code – the ability to freely update or distribute the code in most any way you like. Though you can get your hands on their code if you actually pay for Confluence, you cannot re-use the code in any way other than modifying your version or contributing macros and bug fixes to the Confluence community. The other three all use versions of the popular GPL open-source license and are supported by large, active communities of open-source developers and users.

All four of these wikis require expertise and access to a server to install. To get started quickly and with minimal technology overhead, a hosted solution may be better. Two popular hosted wikis are PBWiki and Wikispaces, both of which have a free version with some limits. An upgraded Wikispaces account is available to nonprofits through Techsoup Stock . Google has recently released Google Sites as part of its Google Apps suite, based on the Jotspot hosted wiki service that they acquired. If your organization is already using the free nonprofit edition of Google Apps, Google Sites is an easy way to get started with a wiki that will be integrated into your other Google Apps services.

Don’t forget to consider the software you already have, either: if you’re using a higher-end content management system to manage your website, like Plone or Drupal, these systems may also offer strong, wiki-style collaborative documentation features.

For more wikis, and much more information, will let you compare a hundred or more different wiki engines. Each wiki is rated on over 100 features. As with any software application, different wikis will be more or less appropriate for different uses.

Getting Started

Once you’ve chosen a wiki engine, you still have a little work to do before you can start writing your pages.

If you want, you can certainly make your wiki open to all comers, like Wikipedia and WikiHow. However, your organization’s procedures, while likely not top secret, are probably something you’d like to keep reasonably private. It’s easy enough to lock down any wiki in its entirety. The real security question to ask yourself, though, is how granular you’ll want your security controls to be. Do you need to be able to lock down individual pages? Do you need security groups, which will enable you to change security settings for a bunch of users at once?

It’s important to define who will create and maintain the wiki information – your documentation. You can, of course, have one person at your organization create all of the content. However, that would ignore the strongest offering a wiki has: the ability for a group of people to collaborate on the creation of content. Letting a larger group create content doesn’t just spread the work out among more bodies— it also allows you to take advantage of more brainpower.

You’ll also want to determine a basic outline for how your content will be organized. This process will likely include a cross-departmental conversation about what should be included in the wiki and how it should be structured. Of course, if you want to start using a wiki in just one department and let it slowly grow to include other departments, you wouldn’t be the first one!

Although it’s a good idea to have as many staff members contributing content as possible, it’s best to choose one person to oversee the organization of the wiki as it grows. This will be an ongoing, active role—your original outline will be a good start, but because wikis allow many to contribute, things will tend to stray from the plan from time to time. The person who does this work, trimming one branch of content, planting the seeds for what will turn into groups of pages on particular topics, is called the wiki gardener . Really!

The last thing to do before opening the floodgates to the whole organization is to ask a small group of people to create as many pages as they can—seeding your wiki with a few dozen truly useful pages will go a long way toward convincing the rest of the team that your new wiki is an important place for both gathering and sharing knowledge.

Jeremy Wallace has worked with both non-profits and technology since 1995, mostly focusing on databases, though lately he’s gotten the impression that the internet might just take off,and he has started helping non-profits with their web needs. He has worked for TIAA-CREF, the Fund for the City of New York, the Center for Family Life in Sunset Park, the Education Trust, and many non-profits as an employee or contractor. Jeremy is currently a project manager at PICnet, is the Director of Operations at Writopia Lab, and still keeps his consultancy alive at ABCDataworks.

Wikis for documentation and product updates

Anne GentleScott Abel, the Content Wrangler, is hosting an article by Anne Gentle:

Anne Gentle has provided a list of wikis she has found that are used for product documentation or to provide new and updates about software products.

Wikis as documentation tools

Jeffrey Tadlock at Cognitive Confusion has written about Wikis as documentation tools:

as being a central place for server config information, tips and tricks on various services we have running and even up to and includng contact information for various vendors. I have a fair amount of it documented already – just in a myriad of text files, word docs, spreadsheets and my mail client’s address book. This should allow us to have all of that in one place for others in the department to look at when needed.

For our case I was trying to decide between MoinMoin and MediaWiki. MoinMoin is Python based, while MediaWiki is your more typical LAMP (Linux, Apache MySQL and PHP) app. I was tempted to go the MoinMoin route as it does get good reviews and it would have been an excuse to get more familiar with Python. But… many of our open source apps currently in use are of the LAMP model. So in trying to keep things grouped together where the expertise is, I chose MediaWiki for our documentation Wiki.

Currently I try to update a little bit in the Wiki three times a week. I have also been using it as a scratch pad of sorts while troubleshooting various issues. Sometimes having those notes from troubleshooting prove quite worthwhile.

Wikis for Supporting Distributed Collaborative Writing

Tech Republic has an article: “Wikis for Supporting Distributed Collaborative Writing.”

Wikis allow distributed teams to collaboratively write and edit documents through the Internet in a shared online workspace, without the need for special HTML knowledge or tools. The flexibility of wiki technology is a boon for increased cooperative work on large team projects. However, wiki technology also complicates notions of usable design as the information architecture of a wiki site may be created on the fly by all participants rather than by a dedicated technical communicator. This paper describes the basic technology of wikis, some advantages and disadvantages, and areas of concern with regard to information design.

This article is originally from the STC. Viewing it on TechRepublic requires login. Or you can read it here, on the STC.

Wikis for internal documentation

Jeremy Wallace at Idealware knows of one good use for wikis—for a company’s internal documentation. Wikis are useful to document information that a lot of people need and that, in paper form, goes out of date. A wiki has the advantage that anyone who notices wrong information can change it. The human resources department, the person who tried to call the old title holder and tracked down the new one, or the new incumbent can all take a moment to update contact information. It can even hold temporary information: “Maria’s on vacation til the end of August — call Krishna.” But it still tracks who made the change, so on an internal company site or “intranet” it’s unlikely to be vandalized.

Read “Using wikis for internal documentation.”

Wikis have a number of advantages. Because they are flexible and easy to edit, you can create information in the format that is most likely to be used and updated. And as with any online application, your staff can access them from anywhere they have an internet connection.

Though you will probably want to keep your employee manual—and anything else that lays down official organizational rules—in a form that is not so easy to update, a wiki can be a great help in creating and maintaining less sensitive information. In this article, I’ll take a look at the strengths and weaknesses of wikis for documentation, and some of the things to consider as you look for one that can help your organization.

%d bloggers like this: