Chaotic wiki vs. structured authoring

Wikis are old, and old are the problems that wiki authors and readers struggle with. Collaborative authoring in wikis might tap new synergies but often the outcome is as chaotic as a humming beehive.  So how can you structure your content? How can you make it accessible? How can you organize reviews and input supply?

This knowledge article is based on the experience gained in wiki projects.

Problems in company wikis

Many company wikis are set up with noble intentions, but many of them get chaotic over time:

Unstructured content

The core function of a wiki is collaborative authoring. If you are lucky (and have motivated your teams), many people contribute to the company wiki. But they have different backgrounds and different fields of expertise. That is why they write in different ways. In the end, authors structure and format the information as they see fit instead of keeping to a common layout. Task-oriented information is not separated from reference or conceptual information making it hard for the reader to understand the purpose of an article at first glance.

Insufficient navigation and access to content

All wiki software products provide features such as categories, tags, and linking. But defining tags and using links is solely up to the authors. What happens? When wikis grow larger over time, it is getting increasingly difficult to find the right article. Duplicate articles are created because authors cannot find existing articles.

Insufficient workflow functions

Writing in a team requires defined workflows. In an unregulated wiki, every article is visible at once. Workflows are often a matter of negotiation rather than being enforced by controlled software processes. This results in wiki pages of highly deviating quality, making it hard for the users to rely on the content.

Why should we use a wiki and not DITA?

Technical writing in XML-based information structures, such as DITA, has solved many of the issues described above. Structured authoring solutions provide topic types (task, concept, reference), mechanisms for organizing information products in maps, relations between topics and metadata for workflow status, target audience, product variant, etc. Content management systems or transformations (as available in the DITA Open ToolKit) deliver output formats that are easy to navigate and searchable.

How can we transport concepts of structured authoring to a wiki? Why should we do so? Are wikis made for structured authoring?

Adopting some concepts of structured authoring for collaborative writing in a wiki may be well suited for companies who wish to organize their writing processes more strictly and to improve the user experience for the wiki readers. A wiki is a good documentation tool especially for those companies that:

• Need to document internal software or processes.
• Want to involve subject matter experts and software engineers in the writing process. while keeping documentation structure and style consistent.
• Want to provide an online documentation and use the commenting or collaboration. functions of a wiki in order to get feedback from their users.
• Do not want to establish an XML writing environment.

Adding metadata to a wiki

Metadata forms the basis for adding structure to a wiki. One possible technical solution is the Semantic MediaWiki, an open-source extension to MediaWiki. Metadata extensions are also available for other wiki software products, such as Confluence.

You can use various metadata for organizing your wiki, for example:

• Index keywords
• Target group
• Workflow information: status, responsible person, priority
• Region and language
• Information about the position of the topic in the topic hierarchy
• Relations to other topics, for example, from a task topic to the associated reference information

Using forms and templates

How to motivate users to keep to a specific topic structure, create DITA-similar topic types and assign the correct metadata? The anwer is: Use forms! You may, for example, provide different forms for typical DITA topic types, such as task, reference, and concept.

Forms ensure that users cannot enter text outside the predefined fields. The layout is rendered automatically as forms are linked with templates. Default text within the fields guides the users and tells them which content to enter in specific fields.

The forms also assign fixed metadata (such as the topic type) and provide fields for configurable metadata, such as the target group or the index keywords. Using a list of predefined index keywords controls tagging/categorization of wiki articles and provides a controlled way of prsenting articles to the users.

Extended functions using metadata

Based on the metadata, you can enhance access functions and navigation in the wiki:

• Scripts can evaluate the metadata on the position of topics in the topic hierarchy. They build tables of contents, breadcrumb navigation, and browse buttons. Wiki readers can use these elements to navigate through the articles belonging to a specific manual, for example.
• Users can use the index terms to filter the topics. The corresponding filter pages can be generated by means of the Semantic drilldown extension, for example.
• Scripts evaluate the metadata information about relations between topics to automatically generate and update lists of related topics.
• Scripts evaluate the workflow metadata and generate overviews, that is to-do lists, for wiki authors and reviewers.

The main point about metadata in a Semantic MediaWiki is that this is an architectural framework. You can define any metadata that you want and then you can query for values, filter by properties, use metadata for searching, for automatically generating contents, etc. What you do with the metadata in the end, depends on your content and on the user experience you want to create.

Is a structured wiki automatically useful?

No, not necessarily! There are additional keys for the success of a company wiki:

• You need to define the purpose of your wiki – is it for documentation purposes, for collecting project information, for organizing the work between teams, for sharing knowledge? If you have a wiki and a second system that serves the same purpose, you need to decide which one to close down. Because here the highlander principle applies – there can be only one!
• Structure and functions of the wiki need to be customized to the purpose. Navigation functions, for example, are very useful in documentation wikis, but not that well suited for organizational wikis.
• You need people for the different roles that are required to maintain the wiki – not just to set it up, because this is only a relatively small portion of a wiki's life time. The maintenance period is usually much longer. You need editors, programmers for extensions/plugins, administrators for backups and installations, and a wiki gardener. A wiki gardener sows ideas, weeds by correcting typos, merging duplicate articles, etc. The wiki gardener supports users in harvesting the knowledge from your wiki.
• And of course you need good content – content that is customized for your target group and the purpose of the wiki.
• The company culture needs to support collaborative working.

Structured, well organized and appreciated in the company – these are successful wikis.