Comments on Using Wikis to Document UI Specifications

Jonathan Baker-Bates — Tue, 14 Jul 2009 17:26:20 GMT

As an aside, I notice it appears several people agree with the idea that Agile encourages people not to document things. I’m not sure I understand that though. It is a fundamental principle of Agile that the team decides for itself how it wants to work, who does what, who needs what to do what they need (the “blockers” of the daily stand-up), and so on. Therefore, if nobody on the team feels the need for UI documentation, then it’s pointless trying to create it. Documentation per se does not help the development process – communication does, and Agile always prefers working code to documentation. If getting to that point in the current iteration needs me to sketch something on a wall, or create a 200-page Visio document, then so be it. If Agile is an excuse not to create pointless reams of documentation, then I’m all for it, but there is in fact nothing about Agile that would encourage or discourage that either way.

Stephanie A — Tue, 11 Aug 2009 23:48:41 GMT

I really appreciate this article, and Terry’s point that Agile methodology is sometimes “an excuse to not document ANYTHING.” Finding a lightweight documentation method is the biggest problem I’ve encountered so far – and I do think a wiki might be the answer not just for a UI spec, but general requirements and details as well. We’ve just deployed a SharePoint-based portal internally, with wiki functionality. It has its limitations, and it’s certainly not the most robust wiki tool I’ve seen, but it does allow multiple/separate wikis to be created and affiliated with specific projects, which is handy. Getting everyone else on the team to use it is a whole other problem!

Juan Hidalgo — Tue, 14 Jul 2009 12:08:57 GMT

Thanks for your article.

I´m Graphic Designer, and wikis tools are very important in my projects.

Again Thanks Peter

JuanHidalgo

Peter Gremett — Tue, 11 Aug 2009 23:48:56 GMT

Terry covered most of the points and I agree with what he is saying. I do want to comment on @Jason #8. The nature of the wiki is that you can create as many pages and sub pages as you like. You don’t have to start off with the perfect organization, in fact this is a bit counter to what a wiki spec is about. They are flexible and should grow and change as the project does. This benefit is really leveraged when you are working with the agile process. The fluidity that is required for this type of project is a good match for the fluidity that you can have with the wiki.

Terry Bleizeffer — Tue, 11 Aug 2009 23:49:03 GMT

@Jason – While I agree with some of those downsides, I don’t with others. On #1, in my company wikis are EXTREMELY widely used by developers… you’d be hard-pressed to find a developer who doesn’t use wikis. On #4, I don’t know what you mean. Of course wikis are collaboration tools… that their major reason for being. We use wikis because everyone can easily edit the same page, and it requires almost no skill to edit. On #7, while it’s true that it isn’t easy to restyle wiki pages (though it’s not hard either, it just requires special wiki knowledge), wikis aren’t intended to be particularly aesthetically appealing, and I think that’s fine for UI specs. We want our UIs to be aesthetically pleasing, not our specs. I completely agree with you about the tendency for wikis to end up with content scattered all over the place that no one ever looks at, and no one can find. I see that all the time. I’m not sure how much of that is a wiki problem though… I think it’s more of a human problem.

Jason Grant — Tue, 11 Aug 2009 23:49:29 GMT

Let’s outline some downsides now as well, since from this article it looks like a Wiki is a be all and end all solution:

1. Wikis are not used widely even by developers
2. Wikis require enormous discipline to keep tidy and consistent looking
3. Wikis can encourage creation of too much data (just like any other social networking tool), and in documentation you want relevant, specific, useful material only
4. Wikis are NOT collaboration tools – crucial point to outline
5. In practice information on Wikis goes ‘out of hand’ and soon people either stop using them or everyone uses the wiki in the way they like, creating a junk resource
6. The fact that the wiki is ‘printable’ isn’t an advantage. More or less everything that is online is printable, but as soon as you print something you have admitted your defeat to the ‘collaborative solution’ you have in place, as paper is not collaborative for non-co-located team members
7. Wiki documents are also usually not that easy to re-style up, meaning that what has been committed into a Wiki usually stays looking and feeling that way (and that way usually isn’t a nice way)
8. Most people do not put in place a proper IA for a Wiki, meaning that the structure ‘emerges’ and this ‘IA by committee’ process can be somewhat messy and produced poor IA at the end
9. In practice, someone has to be a ‘Wiki gardener’ and if you have a team of 5 developers, where one of them is gardening for a big part of his work life, that guy is not going to be happy bunny and it is a waste of resource anyway

I could go on …

Thanks
Jason
www.flexewebs.com/semantix

Paul Reeves — Sat, 04 Jul 2009 22:04:33 GMT

@calum, I use Deki (wiki) for documentation development and as a knowledge base. It allows you batch upload any number of files.
Deki is also the only wiki that supports hierarchy (at least it was when I did my evaluation in late 2008). Thus, you can make nodes dedicated to different docs/specs.
Wikis,in general, are also good on content transclusion so you can define a piece of content once and use it again. This is useful for code samples or feature definitions. It’s helpful to just show inline a relevant bit of info instead of making someone jump around.
Deki also allows you to create templates so you can offer structure for content. I think this is common for wikis but I don’t remember.
Thanks for the excellent article, by the way.

Lisa Rex — Tue, 11 Aug 2009 23:49:49 GMT

The developers I’ve worked with would rather spend time coding than collaborate on the UI in a wiki. If a team is going to go to the trouble of creating their specification in a wiki, they may as well create task tickets for pieces of the UI and assign them to team members.

The Trac Project works brilliantly for this. It has a built-in wiki which is fantastic for communicating high level concepts and essentials like the link to the dev server, but the integrated issue tracking features are great, powerful and easy to use. Once opened, the ticket can be assigned priority, ownership, milestone, component etc. but anyone can comment on the ticket as well as upload files such as PDF and screenshots.

Personally, I find issue tracking to be an organized way to work. Wiki’s can get out of date, but anyone with a ticket assigned them will be keen to the ticket complete, signed off and off their plate.

Daniel Wright — Wed, 01 Jul 2009 18:05:59 GMT

Hackers can break CAPTCHA’s too. I would try to moderate it instead. Or have the user register before they can post an event, like with your article ratings.

Terry Bleizeffer — Tue, 14 Jul 2009 12:09:12 GMT

@ Neil—Ugh, I’ve dealt with that before as well (though not on a wiki). We had a form people could fill out after customer visits that described how the customer was using our product. The idea was that designers could quickly scan through the data to help them make informed design decisions. The form allowed people to attach files, and guess what happened? Instead of filling out the form, people would just attach a Word doc that described their customer visit… which meant anyone who actually wanted to use the information would need to open up every individual form, then open the Word doc, then scan through the Word doc to see if it included any relevant information, then go to the next form and repeat. The result? Tons of information… and completely useless. I think the process solution there involves baseball bats and tire irons.

Neil Heinrich — Tue, 30 Jun 2009 16:57:09 GMT

Great introduction. Collaboration really is key and the options (that I’ve found) are slim.

I’d love to hear more about maintaining your documentation on a wiki. Particularly, wiki architecture and patterns, how it grows, how it adapts, how it becomes the sole source of documentation, who organizes it?

A few issues I’ve had:
- Getting non-technical members to fully sign on to the idea
- Having members upload a doc/pdf “as” a wiki page (kind of defeats the purpose)

There may be a technical solution to the second one.

It would be nice to have a standard solution to the mass uploading of files, via drag/drop into the browser or something.

Chris Baum — Mon, 29 Jun 2009 18:34:51 GMT

@Tom Simpson: We share in your frustration about the spam in Event and Forums. If you know someone who could help implement Recaptcha or something similar, please drop a line to comments at boxesandarrows.com

Terry Bleizeffer — Fri, 24 Jul 2009 15:37:25 GMT

One of the best things about using wikis to document UI specs in Agile is that it avoids the problem of using Agile as an excuse to not document ANYTHING. It’s hard to argue that wikis are too heavyweight for the Agile process, and the collaborative aspect of wikis helps as well.

Most modern wikis have utilities to export a wiki page into Word or PDFs, which helps with the issues of portability and printing.

I agree with Calum about batch upload of images. Our wiki allows me to upload four images at a time, but even that is insufficient at times.

In my opinion, the biggest downside to using wikis to document design is that it encourages static representations of interactivity. Even Powerpoint allows designers easy ways to portray dynamic interactions, and there are other tools out there that are much better than Powerpoint for creating dynamic prototypes. These tools get better and better every year, but wikis force us to pretend that design can be expressed in static screenshots. Sometimes that’s sufficient, but it still feels like a step backwards to me…. like early web apps that forced us to design with one arm tied behind out backs (“You want a combo box? Sorry, HTML doesn’t support combo boxes…”).

(BTW, there’s a typo in the Trust paragraph… “lick of trust”... no matter how much trust there is, colleagues should not be licking each other)

Calum Benson — Fri, 24 Jul 2009 15:35:55 GMT

Biggest drawback of wikis for me, especially with UI specs, is the inability (of any of the ones I’ve used) to batch upload images. The first draft of even a modest UI spec typically involves dozens of images, and it’s a royal pain in the butt to upload them all one at a time.

Tom Simpson — Fri, 21 Aug 2009 20:32:40 GMT

For the love of Pete, can you please CLEAN OUT THE SPAM in the events database?