The Mystery of Documentation

It’s that time again, when my fragile designs need to be encased in a sturdy barrel of documentation and set off down the rapids of implementation. All I can do is hope that they end up at the bottom in one piece.

If there’s one thing that’s constant about documentation, it’s the maddening inconstancy of its form. This seems to be due to the inconstancy of the development process itself,  which is something now gradually being accepted via things like Agile methods.  For example, I was interviewing somebody for an IA position the other day and we talked about what kind of documentation they had done.  To him, documentation is like doing bird impressions:  the lesser spotted prototype, the crested sitemap, the heavy spec. He could do them all to order. None of them was any better or worse than any other. What mattered was whether they were appropriate to the circumstances of the project. Stodgy waterfall methods demand huge detailed documents, while groovy Agile projects demand throwaway prototypes. The IA just produces what’s needed. None were a magic bullet, and none very effective really, and he was the first to admit it. We can only do our best.

So about once a year,  I say something about what kind of documentation I am currently preferring to produce.  I say “documentation” but I think of it as anything that preserves my designs from the ravages of misinterpretation (the aforementioned “rapids”). It’s worth saying that I think this is a useful attitude to take. Any designer who spurns the activity of documenting their designs is a bad designer simply because the best designs in the world are useless if nobody can implement them in the way they are intended.

Over the last 12 months I’ve been doing my design work in Axure to produce fairly high-fidelity prototypes first, and preferably of the entire system so that I can show that to anyone that needs to have an overview.

Once the design has settled down (and because I don’t yet trust Axure’s built-in documentation tools), I take screenshots of the prototype, and create any states of things that I’ve not already created as part of the general design work (error conditions, edge cases, etc.). I then link these PNGs into MS Word documents, arrange them by “layout” and “module” (with nice things like tables of contents) and use Word to apply annotation numbers to the images. These numbers refer to the actual annotations, which live in a spreadsheet. The reason they live in a spreadsheet is because that’s how the BAs like to work.  Spreadsheets can be sorted, and requirements tagged and bagged and put in/out of scope with minimum fuss. It wasn’t my idea (I’d prefer to have UI-related stuff in the same document as the UI) but it’s worked fairly well so far. Non-UI stuff is in that spreadsheet too.

If I have time, I also like to create short introductory videos (using Jing) demonstrating the Axure prototypes and talking about them in a sort of droning slightly nasal tone. This way, if anyone wants an overview, but hasn’t got time to meet me face-to-face they can get the next best thing.

I describe complex interactions with state transition diagrams (using Visio). I’m confident that these are usually clear because they’re simple, but whether anyone uses them I don’t know. One problem I’ve found is that developers sometimes can’t understand what I mean by a “state.” I can only mean UI state, not system state, but sometimes that seems too abstract for them.

Graphical site maps are usually a total waste of everyone’s time, and I’ve not done one for what might be three years now. Although that may be because I’ve not done a ground-up complex web content design for a long time. However, I recall that when I was doing such design, the site map (if it wasn’t simply a spreadsheet) was still a phenomenally poor use of time.

There is still the uncracked nut of content of course. No real progress there apart from storing content in the aforementioned spreasheet. I note from some user research last week in Japan that our localisation in that market is seen as poor. I feel partially to blame for that, but have so far drawn blanks. I remain hopeful a decent solution can be found to allow translators to see content for UI appearing in context without losing track of it further into the localisation process. It does constantly amaze me that those who create content management systems seem blissfully unaware of this massive problem – rather hard to exaggerate in fact.

Handling change quickly after the “final” version of the spec is usually also messy and somewhat painful, and could well deserve more attention.

And that is about it for the yearly report. This year sees me heading into proper Agile territory though, so I expect things to keep changing.