The Need for Constant Updates (Wikis)

by Tom Johnson on Jun 12, 2012
categories: wikis

Not only did the need for shared ownership push me away from Flare and InDesign toward wikis. Another element encouraged me in this direction as well: agile software methodology.

Agile software methodology is a method of creating software in small releases to get feedback that helps inform the next release – proceeding to build the final product little by little based on iterative feedback rather than spending two years in seclusion working from a list of requirements that are out of date once you finally release.

We released a new version of the software every month, sometimes every two weeks. As such, the documentation was continually evolving. I began to follow a more agile writing process. As I participated in training for new users, it would always surprise me that no matter how well I described tasks and processes in the documentation, users had questions. They used the application in ways I didn't fully anticipate. Terms confused them. Step sequences were not easy to follow. They couldn't find information. Some tasks needed to be more visible. Who could anticipate all of this beforehand? As much as I tried, the documentation always needed adjustment.

Based on the feedback from training users, I changed the documentation, making it better and better with each released version.

I even hosted my documentation on a separate server so that I could update documentation on the fly. I wrote about this in a post titled Two Stories About How to Write Help. This iterative authoring approach seemed to align perfectly with agile software methodology; it presented a fundamentally different philosophy about how to approach help.

The traditional method of help authoring is to think you can write all the help you need before the application is released. The assumption is that the writer can anticipate all the user's concerns and needs, and so basically you're done once you release. You can move on to another project.

In contrast, the agile writing method suggests that information should evolve following a continually iterative process. One needs to publish and get feedback, publish and get feedback, and in so doing move closer and closer to a state of documentation that is more accurate and helpful for users. This state of documentation isn't something that one achieves on the first try, or even the second or third.

Why does documentation need to evolve continually? It comes down to limits of perspective. The idea that documentation can be produced by a single person working from a single perspective in a single department is a flawed idea. Only overly confident technical writers blinded by their insider's perspective would think this way. You have to carefully monitor feedback from multiple perspectives and make updates over a period of time post-release. I wrote about this in a post titled, A Reverse Approach to Documentation. With the initial release, you include only a bare-bones set of documentation. As soon as you begin alpha testing, you listen carefully to user feedback and problem areas, and that's when you focus your energy with the documentation.

These two trending needs – the need for collaboration, and the need to make constant updates to documentation – persuaded me that I needed to adopt a different method for help authoring. Using a help authoring tool to produce static files that only I could edit felt like a dated authoring methodology that would ultimately become a thing of the past. I needed to adopt a method that was more dynamic. With this, I decided to move from Flare and InDesign to wikis.

Next: 1.2 Some Wiki Basics (Wikis)