Functional Specifications

I’m three weeks into a brand new project, and my mind is on requirements and specifications. Like every project I’ve ever worked on, this is unique. This time, it’s unique because it was half documented and thought about, and was then mothballed. Now it’s back from the dead a year later, and I’m on the case trying to make sense of what was done. There’s one person in my department who worked on it before it was frozen, but the others (who wrote most of the docs) have gone.

The project is a complex one in terms of function. One half of it involves designing a fat client interface (a .NET application) that talks to a proprietary CMS to allow the editing of very specialised content types. The other half is a web-based management interface to the CMS for use mainly by reviewers and approvers of that content. After almost three solid weeks of reading, talking to people and firing off emails with questions, I still feel pretty shaky on the details, and even some of the broader concepts. The feeling of not knowing what I don’t know is also rather annoying.

So the one thing that I really, really wanted to find in all the proposals, presentations, use cases, wireframes, process flows, action matrices, prototypes and other wonderful artefacts that have been produced on the project over the past few years, was something that just gave me a general overview. This would preferably be in writing, describing what the system currently does. No such luck. The collective knowledge of the team is the best I can hope to fall back on.

I know that this issue of “the big picture” on projects has been taxing the minds of the great and the good, and I’ve been comparing two approaches on the last couple of days: that of the famous Joel Spolsky, and the less thorough, but admirable opinions of Jason Fried the head honcho of 37 Signals.

Both make good points. I tend to feel that Fried is playing to the gallery a bit in the sense that interaction designers and other “experience architect” types dislike words and prefer pictures to communicate things. That’s fair enough – pictures can and do convey a lot of stuff on most projects. But without some underpinning of clear context, and cross-reference to detail, it all falls apart as surely as 500 pages of dense Times Roman. It just does it in a different way. This issue came to me unvarnished when, after being assured by the handover document that wireframes had been “completed” for one half of the project, I opened the relevant file only to find 85 pages of expertly crafted pages almost completely unannotated. Just pictures of pages in space. At that point, I knew I had my work cut out.

The 37 Signals position is also coloured by the the fact they’re consultants, and don’t have to deal with history, politics or even much economics. Reading many case studies in which they and people like Adaptive Path have been involved, you can’t help thinking they just make up their own rules, go in, do a spectacular job, and leave. Spolsky’s view is more pragmatic. He insists on writing at least some things down because he comes from an in-house tradition of dealing with the political backdrop to software development. Written documents can have a certain corporate symbolism that commands respect. That can of course be used to hide behind (and lord knows the “use cases” I’ve been reading today – written by a third party in this case – are utter sand bags). But their main utility is positively to deal with a set of problems. some of which might not have anything to do with the project directly.

When I suggest I write a short functional spec to “set up” the other artefacts (primarily wireframes, process flows and things like data dictionaries) along the lines of a Spolskly example, the first reaction is that nobody will read it, and the implication is that we don’t need to do it as long as our other artefacts are detailed enough. That may be true, and in this case I’m a latecomer to the project willing to take a back seat unless things get really messy. But what’s interesting is that conversations about terminology and vocabulary come around regularly on the project, and this usually ends with somebody wishing we had a “project glossary” to pin down the definition of something. Yet I know from experience that if you attempt to write such a document, you realise that in fact you need to write a spec because once you’re on that path, you can see the light that a little context provides. No matter how detailed a wireframe or a site map or a business rules document is – if the reader doesn’t understand the context, it’s pretty much worthless. There is no substitute for words when supplying that context. It just takes a bit of faith.