Recently I kicked off a web app project for a client; something I've done countless times before on projects of varying scale & complexity. This got me thinking that it might make a good post to talk about the tools, techniques I use and the hopes/fears I have at the start of such projects. So here goes!

We've all got our own processes for coming up with a proposal so I won't go into that now; instead I'm interested in the bit where the wheel meets the road; you've agreed to work on a project and at some point your sat down thinking "errr...ok...where do I start?!".

The Client's Spec

9 times out of 10 there is some form of client spec floating around (after all, you quoted for the project?!) so my first task is to see if it holds water, specifically I'm looking for:

- bits I don't understand

- areas where my spider sense tingles and I know there will be issues (cans of worms)

- areas they've forgot to go into 

- opportunities they've missed

...in short the detail.

This typically means then I've got to create my own set of documentation (that's always an awkward conversation, client: "but we've done the spec already?", me: "....errrr...yeah...about that"). What I create depends on the project but can consist of:

- my own spec which details the project, the phases it will go through, the general overview of what we're achieving etc

- sitemaps

- wireframes

- web doc (puts a bit more flesh on the bones on the above, perhaps a bit more techy)

- data docs (some times I like to map out all the areas where data is needed and which forms use them etc)

- narrative(s)

- misc stuff

Now which docs are useful to the client is a moot point - it sort of depends. I mean, some of the documentation I might start (but not finish) simply because I find the process of writing stuff down is a good way to clear my thoughts - I can then go back over the docs and and additional layers of information. Either way the information created will flow into the project in some form

Obviously I agree with the client some documentation as I want that signed off (ever tried to build without a spec? Nailing jelly to a wall spring to mind?). This is kinda where my tech spec comes into play - it's an amalgam of documentation I've done, pulled together as a collaborative, communication exercise with the client.

I always try to write my stuff is pretty clear English (unless the audience will defo be techy and then I can let loose a bit). 

My Tech Spec

Sitemaps

These normally get thrown into the mix. I like to have a model of the "pages" on the site (even if, in the final version, some pages are actually consolidated into one screen). It can help as a communication device as long as you can explain to folks what they're looking at. Sitemaps/pages are all coded  to help cross-reference to other docs. On sitemaps I may even colour code or use different symbols to indicate SEO work, CMS, database driven etc.

Wireframes

I find these handy. Again it helps get that light bulb to come on for clients (many people just cannot read things - they have to see - we're all different). These maybe lofi mockups or I might even get a designer to get more slick ones. EIther way they'll be crossed referenced to all other docs. The wireframes will form the basis of the actual design 

Web Doc

This doc sometimes comes into play. Basically there willl be a section for each page on the sitemap. For each page I'll give a narrative of what's going on, what functionality is on it. I might exactly list out all the fields etc. 

The web doc could be part of the tech spec but I sometimes keep it separate because the section numbering can get confusing (the section numbering in the web doc needs to match the codes used on the sitemaps/wireframes)

Data Docs

Sometimes I like to keep a track of what data is being displayed in various forms on the site. This helps iron out wrinkles like "oooh! so the customer number on the the order form is the relationship code in the management console?!" etc. Unlike the other docs these'll usually be spreadsheets and probably not shared with client.

Narratives

Sometimes none of the above documentation makes a lot of sense to the client and their stakeholders; in which case a narrative may help. I like to do this anyway; it's a plain Enligsh, non-techy walk through of how the system works. All stakeholders should be able to easily understand it. I'll use it to generate feedback and to help elicit scenarios which are not convered (I'm always looking to throw light into the dark areas of the project - I'm scared what might be lurking there!)

Wow! That's a lot of documentation

Yeah BUT only a portion of this will be signed off by the client and many projects will not have this much. 

Also, I may not complete all the documentation; I'll start off with the best intentions to create a set of documentation that will be 100% water tight. However, life isn't like that. I've learned when you need to be happy that you've done enough and be happy that you've thrown enough brain power at the problem landscape; looking at it from as many angles as you can to find the killer, gotcha issues. Yes you'll probably hit a few bumps in the road later on in development but as long as there are no more show stoppers then documentation has done it's role.

But what about AGILE etc?

Most people will spot that I'm trying to do documentation up front here - this is pretty classical approach. Perhaps that's because it works best on the size of projects I'm involved in (many are just me and a designer, some involve other techies) or perhaps it works best from a billing and client point of view.

I'm very interested in what tools and techniques you ladies & gentlemen find useful.