Using Wikis to Document UI Specifications

Written by: Peter Gremett

Introduction

The role of the interaction designer is to specify the interface’s behaviors and elements, so that engineers know what to build and how the product should operate. This documentation is commonly known as a UI specification or UI spec. There are several applications for authoring a UI spec, with wikis being a relatively new tool. However, designers should be aware of a wiki’s benefits and drawbacks for documentation, since UI specs uniquely reflect a project and its context. The documentation needs are often based on the size of the project, launch date, team dynamics, audience, technology, and the product development process. The development process usually plays a major role in how teams interact and how work is completed or delivered, thus, there is a direct relationship between the UI spec and the process the team is using.

Description of the Problem

There are many product development processes and one that has garnered much attention is agile. Agile refers to a group of software development methodologies that promote the project development lifecycle through iterations, open collaboration, and process adaptability. It moves away from traditional process-heavy methodologies and instead focuses on quick actions and an evolving plan as steps are taken.

The Agile Manifesto[1]:

  • Individuals and interactions over processes and tools
  • Working software over comprehensive documentation
  • Customer collaboration over contract negotiation
  • Responding to change over following a strict plan

Many claim that agile methodologies help companies increase revenue, reduce costs, improve quality, ensure compliance, and drive innovation throughout the product lifecycle. As designers, we often find ourselves working with teams that are using agile processes. I propose that the UI spec is best documented through a wiki when working in such an environment. This method is both adaptive and sufficient for teams building and delivering products, and helps to foster the collaboration that agile development requires. Problems with traditional UI specs include the following:

  • Documentation is expensive to write and maintain
  • Encourage a waterfall methodology
  • Slow downloading time for documents filled with tables, images, and cross references
  • Difficult to facilitate collaboration within the document
  • Rely on one central author to write and maintain the document

Wiki Overview

Before you can write anything you must have wiki software[2] established on a private server. There are many articles available[3] to help you choose the right wiki software[4]. Once you have the software installed it’s time to get going! The quickest way to make progress is to create a template that you can use for every project. A basic template frees you from having to repeatedly format a wiki page each time you begin a new project. You can modify your starter template and learn what format works best for you and your team. Template elements to consider include the following:

  • Table of Contents: A list of topics related to the project in order of appearance.
  • Tea List and/or RASCI Model: Owner, accountable person, or support role on the project; someone who provides input or expertise on its outcome.
  • Issues Section: Captures running problems or questions that need to be resolved.
  • Tables: How to layout information in a grid format.
  • Titles: Attributes such as bold, color, size, etc.
  • Subtitles: Attributes such as bold, color, size, etc.
  • References: Links to related information resources.
  • Figure References: How you refer to a figure or diagram within the document.
  • Images: Thumbnails and full images, as well as defining rules for opening a new window.

As you gather information and ideas, you can document them in the wiki. The nature of the wiki makes it fast and easy to record ideas, which helps to spawn additional ones and encourages participation. This process allows you to have a repository that can be easily reviewed by your team members. Undoubtedly, the wiki spec will start conversations among team members both online and in person. As you add more detailed material, your team members will be more likely to contribute. My experience has been that if someone needs clarification on a topic, they are vocal about it and team members will make sure the required information get added to the wiki. Before you know it the spec will be complete.

Benefits

Collaboration

Collaboration is the single best advantage of a wiki spec over a traditional one. The supposition of a wiki is that there are many authors and contributors to the document, and therefore, you have the right environment for collaboration. This is a huge advantage for product specifications. As the interaction designer you don’t have to sit in a cube by yourself and define everything on your own. It’s fine not knowing all the answers and you can rely on your team to help fill in the blanks.

Team members can add clarifications, details, or make edits to content. Oftentimes, the details and clarifications build upon one another to complete the document. For example, if the designer has specified the layout and behavior for a button, the tech writer can add in the rollover text without disturbing the designer or the flow of the project process. To follow the example further, the tech writer can then add the help content to the wiki, allowing the engineer to upload the information onto a server and post the URL. The transparency and collaboration are quite amazing. Team members are able to get the information they need to perform their jobs and help the project along.

Speed

Speed is a major benefit of wiki specs. This is also why it’s a good match for agile projects. Speed comes in two forms: writing and consumption. It’s easy to add content because of the WYSWIG interface. As you begin writing content, it can be instantly viewed by team members. I have found that the sooner you post sketches and thoughts the better. It gets the whole team collaborating and they can offer feedback immediately.

Flexibility

A wiki spec is extremely flexible. This characteristic allows you to morph its structure and organization as the project evolves, reflecting the nature of agile processes. The team is able to keep up with the changes that occur in an agile project because all edits can be instantly viewed. Additionally, if anyone wants to be informed of the most recent wiki changes, an email notification system can be set up by any team member.

Reversible

In the event that a change was accidental or a major disagreement arises, the wiki spec can be reverted to its previous version. This does not happen very often, but when it does, it’s a real life saver.

Figure 1: The image above shows the wiki revision history, including the date and time of the latest modifications.

Archives

Since wikis are hosted on a server by your company, the spec can have a longer life beyond the current team assigned. This living archive allows new team members to get up to speed quickly, and helps them understand how the project has evolved.

Centralized Image Updates

As they say, “a pictures is worth a thousand words” and the old expression applies to UI specs as well. No spec would be complete without images to help the team see what it is building. Once an image has been uploaded it’s easy to update all instances of that image. All that’s required is uploading a new image with the same name. This step saves time for team members and interaction designers, since we’re usually creating screen mockups as we go.

Informal Approval Process

A team typically has an approval step or sign-off for a UI spec. This is often used to ensure that all issues have been resolved and everything has been documented to the team’s satisfaction. With wiki specs this step is unnecessary, since team members have been participating in writing the spec all along. This saves time and the formality of having a spec review. If the team does insist on a spec review, you can capture notes and issues in real time as the meeting is occurring and everyone can easily see the discussion progressing. As issues are resolved, the wiki can reflect the updates and decisions that were made after the meeting is adjourned. Team members can then modify entries and resolve any issues that remain outstanding.

Challenges and Solutions

Installing the Wiki

If you are lucky enough to have either the technical prowess to install the wiki software yourself, or have someone on your staff do the work, then you will have overcome the first hurdle in wiki specs. There are many free wiki software programs available online, so you might be able to skip this first step all together. However, if you are working on anything that is propriety or secure, I would not recommend hosting it on a third party site. You might be exposed to competition or legal issues, not to mention someone else will have your product specs.

Syntax

Another consideration is that wiki contributors must learn some syntax. This can be off-putting for non-technies, but the syntax is not difficult to learn and is similar to HTML. Many wiki software programs make it easy by providing a WYSWIG interface that allows for basic formatting while creating the syntax for you. This lets you focus on what you are writing rather than the syntax. Other ways around learning or creating complicated syntax is to pilfer code from another wiki template by simply copying and pasting it. If copy appears incorrectly, you can remove it or revert to a previous version. Wiki syntax also forces you to keep the document simple rather than spending time writing syntax for a spec.

Figure 2: This interface shows the code created by the WYSWIG editor.

Portability

Some people like the capability to read and write documentation wherever they are. With wikis you have to be online for either of these activities. Even though connectivity is increasing, most companies have firewalls or VPNs that can make access more difficult.

Simplicity

Some designers take pride in their documentation and deliverables. They spend a significant amount of time creating deliverables that are functional and beautiful. Wiki specs do not support this capability. They are essentially text editors that can be used to make documents more appealing by adding images, but they don’t really support the easy customization and flexibility that some designers would like to have. Images must be added one at a time and wikis don’t support many file formats. This may limit a person’s creativity in designing the document.

Printing

You may often see people printing traditional specs so that they can read them during their commute or at their desks. Wiki documents can be printed but they lack the basic characteristics that you would find in a traditional spec. Most of the issues involve pagination. Images get bumped to the next page unexpectedly or tables are displayed across multiple pages. This makes reading difficult, but it can be done. Although I do understand why some people like to print, I would argue that it’s not good for the environment and you should try to work on screen as much as possible. However, the functionality is there for those who prefer to print.

Trust

Trust is a major factor among team members. Some projects outright fail because of the lack of trust among individuals. Wiki specs can exacerbate a trust issue because team members have editing capabilities. If a lick of trust exists among your colleagues, you may see this manifested in the wiki via reverts and lots of edits or re-edits. This can be time-consuming and frustrating. If you have trust issues with your team or certain people need their roles clarified, you might want to consider an alternative method rather than a wiki spec.

Conclusion

Today’s economy and globalization are forcing companies to accelerate growth and increase revenue. In order to meet these demands companies are using new methodologies like agile, to bring products to market. As interaction designers we find ourselves working with these processes and playing an important role in the creation of new products. One of our major contributions is the UI spec, and the best way to document it for agile projects is through a wiki. It’s adaptive and allows for a collaborative experience.

References

1“Agile Manifesto”:http://www.agilemanifesto.org

2“List of Wiki Software”:http://en.wikipedia.org/wiki/List_of_wiki_software

3“Wiki Engines”:http://www.iterating.com/productclasses/Wiki-Engines

4“Wiki Feature Comparison Table”:http://www.wikimatrix.org