Comments on: Using Wikis to Document UI Specifications

By: gameraboy

gameraboy — Wed, 30 Nov -0001 00:00:00 +0000

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

By: scottishwildcat

scottishwildcat — Wed, 30 Nov -0001 00:00:00 +0000

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.

By: terrybleizeffer

terrybleizeffer — Wed, 30 Nov -0001 00:00:00 +0000

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)

By: baumr1

baumr1 — Wed, 30 Nov -0001 00:00:00 +0000

@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

By: nheinrich

nheinrich — Wed, 30 Nov -0001 00:00:00 +0000

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.

By: terrybleizeffer

terrybleizeffer — Wed, 30 Nov -0001 00:00:00 +0000

@ 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.

By: danielwright

danielwright — Wed, 30 Nov -0001 00:00:00 +0000

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.

By: lisagreenux

lisagreenux — Wed, 30 Nov -0001 00:00:00 +0000

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.

By: bohappa

bohappa — Wed, 30 Nov -0001 00:00:00 +0000

@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.

By: flexewebs

flexewebs — Wed, 30 Nov -0001 00:00:00 +0000

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
http://www.flexewebs.com/semantix