Demo Showcase Suite – A History – Part 3

In my last post, I detailed 10 things that were on my mind when we started the project.  I’m going to go into a little bit of depth on those now.

1.  I wanted specs that were easy to write, easy to read, and easy to maintain.

I’ve done a lot of projects, in a lot of styles.  My first project was back in 1994 working for EDS on a General Motors project called ASPEN, building the new Assembly Line Support and Production Environment.  To this date, it is still the largest project I’ve ever worked on, even though I was just a minion on the production support team running the nightly builds, managing the source code repository and fixing bugs.  It was a typical waterfall project with 60+ developers and analysts and thousands of pages of specs written and managed by an entire team of people.  That works great when you have an entire team of people to manage the docs.

Most of the rest of my career has been on projects with 5 or fewer people on the team, where once a spec was created, it was forgotten about, or rarely ever referred to again after the initial development was done.  In one of the projects I worked on last year, the specs were pretty sparse, the details and functionality hidden in poorly formatted emails that were chopped up and inserted into a Word doc.  Some emails never made it into the docs.  Some changes were done by a phone call request or hallway conversation.  There was no continuity, and the specs were never maintained after development began, even when change requests came in from the customer.   Scope creep was inevitable, and it led to a lot of issues in the final release as to what was, and what wasn’t supposed to be included in the final deal.  We had to hunt through email to figure it all out.  That memory was fresh in my mind when we started Demo Showcase, and I vowed to prevent that from happening again.

Still, with a small team, limited time, and final requirements that weren’t yet ready, I couldn’t implement full fledged specs.  I started simple, using very simplified UML diagrams like the following built in Visio:

I stole this concept from someone else’s blog (don’t remember where now, or I would pass the credit).  My wife, who is a project manager by profession, had never seen something like this, and really liked it.  It allowed me to build up a list of high and medium level functions and to group those functions into our release plan.  We could easily sit down with the customer and review what would, and wouldn’t be in each release, and walk through the app functionality.  We took this diagram into meetings with a projector, edited it, and moved things around.  If something needed a deeper level of documentation here, we added it, but in general, two levels was enough, and we never went deeper than three.  If a function had more than three, it was a candidate for a ‘use case’ of its own.

It’s extremely easy to train management, customers and developers to read this diagram.  It’s almost obscenely easy.   The only problem I had was with Visio trying to move the bubbles around for me when I was adding a new one.

Once the diagram was flushed out, we split up the work between three of us (the Project Manager, the Product Owner, and myself) to create a set of Word documents with more detail for each function, which became, not coincidentally, the Functional Spec.

For each level 1 bubble (use case), we had a section in the document.  This document was maintained throughout the project by the QA Team and the Project Manager.  It had a change log at the top, and changes were tracked.  We did a final walkthrough of each document prior to starting the development on that part of the project that caught a lot of issues. That’s not to say we had completely flushed out all the details, but it was amazing how much we could put down in a short amount of time.

The QA’s test cases came right from this document.  If there was a discrepancy between the test and the app, the document won out, or at the very least, it was updated to reflect the change.  If changes started to sneak into the app without being updated in here, the QA knew pretty quickly.

Again, this document didn’t go down to the line level in the code, but if there was a particular architecture I wanted to use, a trick in program flow, or some other note I wanted to add, I put it in here.  No searching around for miscellaneous emails, no arguments about who told who what. 

I’m not saying this was perfectly executed all the time, but our QA’s did an excellent job of holding both the developers’ and the PM’s feet to the fire and trying to keep this in good shape.  Hopefully, on the next project, and the one after that, this becomes second nature, and it just gets done.

Of the things we did right on this project, this has to be at the top of the list.  Before we did this, we were headed down a very chaotic road, and the developers had that look on their faces that signaled we were in for a mutiny if we didn’t get our management act together.  This at least put off the mutiny for a couple of months.