Wiki/Issuetracker versus documents

x

One of the discussions I often encounter in my attempts to help projects improve their tooling, is whether to stick to classic document based documentation or move to a Wiki based documentation platform, supported by a issue tracker.

Most projects actually use a mix of documents, wiki's and issue trackers. Typically the different documentation (meaning online information in general) tools are used for:

• Documents (MS Word, OO Writer, Google document): Documentation in general, in particular the documentation defined by the development process or as deliverables to the customer.
• Spreadsheets (MS Excel, OO Calc, Google Spreadsheet): Used for 'things to do' like task lists, backlogs and actions together with mapping information, like requirements, test, etc.
• Wiki: Wiki's are primarily used for information close to the application development, like updated infrastructure info, development guidelines, build information, etc.
• Issuetracker: Primarily used for bugtracking.

This 'rich' ecology usually isn't defined by an analyses of how to create an effective tooling platform, but grows out of an ad-hoc need for written information into a online media. This means the information media is chosen based on the rather narrow criteria of what seems most natural for the producer of the information at the time, or in case of process defined documentation, what seems most natural from a organisational point of view.

The problem here is that this approach usually leads to a fragmented information system with documentation being spread over a bunch of decoupled medias. The result is that a lot of time is use on producing and maintaining documentation, which on the other hand is rarely used because of the difficulty in find relevant information.

Instead I'd like to take at step back and take a look at the general qualities one should look for in a good collaborative documentation setup. One of the first steps here is to limit the amount of different medias used for storing information. In the following I will try to argue that document based systems have a number of critical limits, and a wiki/issuetracker based system is a far superior choice.

Here is my list of the most important priorities for a good project information system.

1. It should be easy to find information. The value of documentation is directly related to how much it is used. This means that the value of documentation which is difficult to find, is of very little use. This is both the case for specific information I may be searching for, but also information which might be relevant for my work, but I'm unaware that it exists. 
2. It should be easy to contribute with information. The quality of the information in a project is very dependent on the barrier to getting the information from your mind into a persistent media. The more time and effort you need to invest in writing down a piece of information, the less likely it is that is will be added to the project documentation.
3. Easy access to change information: The amount of information in a project will rise over time and it will quickly become impossible to keep track of all the documentation in the project. Instead project members should be provided with the ability to track the changes to the documentation, which is much easier to cope with. Another benefit of focusing on documentation changes are that this information reflects the areas currently being worked on and are naturally a good point of focus for project members.
4. It should be easy to focus on the relevant documentation: This is a crucial component in the effort to be able to work with growing amount of information as the project ages. Here it is important to provide focused views on the areas of the project relevant for a given context. Examples of contexts are: backlog, a given feature, a release, architecture, regression test, a given build, my tasks, etc. All these contexts reflects different crosscutting aspects of a project with overlapping information.
5. Information processing: A lot of the information found in project can be automatically deferred from other information, which is is much better than having to manually produce the information or ignore it. 

A tooling setup which contains these qualities will provide a solid foundation for a project, where a suitable process framework can be added.

So let's take a look at the ability of the different tools to provide the capabilities listed above.

Find information
Information in both document based systems and Wiki/issuetracker information systems can normally both be located by transversing the hierarchical document structure or by free text searching the information (unless you store the document on a simple shared folder). This is okay if you know precisely what you are looking for. But a lot of the useful information we acquire are interesting stuff we stumble across while looking for other things. This typically happens when you browse a website where the hyperlink nature of the documentation allows you to freely lookup more detailed pages describing related information. As the internet shows, this way of build 'clouds' of interlinked information provides a superior user experience compared to a hierarchy of decoupled documents.

Because wikis and (most) issuetrackers are websites in nature, they can take advantage of the webs possibilities for construction integrated information models, where the user can explorer the full information as he choses. In a document based information system you are much more locked into reading the information top to bottom in the sequence defined by the author of the document.

Contribute with information
Let's turn to the differences when adding information to the documentation. The simplest way of allowing users to modify documentation is to make it possible to edit directly in the text or graphics being viewed. For simple text modification to a document or wikipages this is trivial, but what if you want to change the structure of the information elements, eg. split a document in 2, relocate or rename a element. These types of 'refactorings' are performed all the time in wikis and issues tracker, but are rarely seen in document based systems because of the more static nature of the structure found here. This means that an evolutionary development (agile) of a projects information model comes much more natural in a wiki based system than in a document based.

Change information
Both document based systems like Sharepoint/Google Docs and wiki/issuetrackes provide functionality for view change information and subscripting. The main difference here are primarily that the change information typically takes the form of dynamically generated webpages, so it integrates naturally to wiki and issuetracker content, where it more functions as 'metadata' in a document management system.

Focused information
Here we find one of the main differences between the 2 documentation approaches. Because wikis and issuetracker systems have a nice separation between model, logic and view, all information can be collected together in one big shared model, and a infinite number of specialize view can be generated. In a document on the other hand the author writes the view directly, so the only one static view is available. The data contain in the document is also localized to the document, and can not be used by other documentation elements, so the information needs to be written again if they need to appear in other documents.

Generated information
The advantage of the separation between data, logic and presentation is again clear. Here wikis, issuetracker and other webbased applications are able to draw on the full information model for data, and usual comes with extensive out-of-the-box project information processing capabilities. Spreadsheets have a limited capability for processing the data found in the spreadsheet itself, but more ambitious efforts to manipulate the spreadsheet data can quickly become a development project by itself.

Integration
To provide rich views in the different tools including information from all relevant areas of the project model, the tools need to be able to display information from the external models contained in the other applications. This can either be accessing the data via webservices or by embedding graphical components from the external tools (widgets/gadgets). These kinds of integrations are an integral part of Wikis and issuetrackers, but are difficult in documents.




On paper the document based system may perform better than described above. It is possible to link across documents, it is possible to refactor document structures, it is possible to embed advanced functionality into documents etc.. In the real world these features are rarely used, and even rarely used with success, because all these functionalities fall outside of the basic nature of documents. That said, we have seen an effort to integrate many of the advantages of the webbased systems into document management system. The most successful challenger here is Google docs, which takes a big step towards making a collaborative document based informationsystem a reality. Many of the document based documentation short comes remains though.

See Tales from history of documentation for a more historical 'analysis' of the nature of documentation.