Sebastian Deterding — Fri, 07 Jan 2011 19:49:10 GMT

Hi Peter,

thanks for opening the discussion.
In response to the scepticism of some commentators, I’d like to share a wiki war story: We’ve recently used a wiki as primary documentation tool in a large news site redesign. In retrospect, I would always do it again.

Pros ====
1. If elements are named/ID’ed consistently, internal search of the wiki becomes the killer app of the project. Our developers *loved* it.

2. All important information on a screen, process, screen element can be filled in on one wiki page, from business goal to technical implementation details and testing fixtures. That’s great for overall documentation management, regardless of the development methodology you use.

3. Automated revision handling. Really, it saves enormous work.

4. If you do everything right, you can hand over a comprehensive site documentation to the customer that his developers, product managers etc. can work with and continue to use right away. A hidden major asset.

Cons ====
1. If you already did a large amount of design work before the wiki is introduced (we did), chopping up and converting all those documents & images into wiki pages is a really, really mean task—but worth it.

2. If you work with annotated wireframes, each time you change anything within the wireframe, you have to download, change & reupload the wireframe file. A *major* hassle. We put the annotations in the wiki text and the annotated wireframe graphic as a Visio attachment + png screenshot of Visio. We didn’t find a good tool that would allow to change the annotated wireframe within the wiki, but for future projects, we’ll look into balsamiq (we used Confluence).

3. You have to spend a decent amount of time beforehand to think about the structure of the wiki, the structure of the pages, the TOC, the attachments, set up layouted page templates that people can copy and paste etc., to train project members in these standards, to enforce them and regularly clean up the wiki – and you have to have your customer allot time and budget for that :).

Caveats ======
1. *Do* create a consistent unique identifier for each and every page and page element (i.e. “P1” Registration page, “E14” Small content teaser etc.), and have somebody mercilessly enforce the use of these identifiers from design to testing. Each page and each page element gets its own wiki page.

2. Include process documentation in the same wiki (project plans, team list w/ roles&responsibilities, etc.), but keep it organized apart from the product documentation (wireframes, process flows etc.).

3. People don’t look into attachments. It’s true. If you want to communicate an information, put it visibly on the wiki page. No “the page flow is attached here.” will do.

4. Beforehand, check with your client whether he wants to use the wiki after the project is completed, who is going to use it, and train those people in how to use it.

Boxes and Arrows: Comments by Sebastian Deterding