I’ve recently been thinking a lot about the deliverables that are required for software projects.  Amazingly there are projects out there that are running with out any concept of what there deliverables are.  Yeah, we all know that we’re supposed to be delivering some sort of software, but beyond that what is it that your project needs to deliver to the client?

I would suggest that the non-software deliverables will vary depending on your client’s bureaucratic needs, their support mechanisms, legislation adherence, who the final audience is and any number of other factors.  If you’re delivering an internal facing software service, you probably need good API documentation for the other developers who will end up being your users.  Contrast that with a situation where you’re building software for a government regulated industry.  I haven’t had the opportunity to work in that situation, but I’m sure there would be a lot of paper deliverables and they’d probably range from screen designs to algorithm documentation.

Most of us assume that it’s easy to determine the deliverables that we have.  As developers we instinctively say things like “The code is the documentation” or “There are comments in the code that explain it”.  While these can be true, it is so only for a select audience.  What of the people, oh, let’s say the business case owners, who don’t have Visual Studio or Eclipse on their computers?  Without being able to view the code (not to mention that they probably would be drowning in the syntax and design) how are they to get the information that we developers so meticulously insert in?  From a developer’s perspective it’s easy.  Because we can, we just go look at the code.  The Code is the perfect deliverable for us. 

The thing is, the code isn’t a deliverable for the business user.  A working application is, but raw code is not useful to them at all.  They need something that is created with them as the primary audience.  They need something that they can easily translate into their own terms, if it isn’t in their terms already.  For them you may end up creating use cases, system flow diagrams and specification documents.  People working the support desk may require a completely different deliverable that the business user.  The folks in charge of the emergency restore plan will definitely need a different set of information.

There is a catch here though.  These people will never come to you and ask for these documents.  Most of the time they don’t even know that your project exists.  To be a conscientious professional you have have to go out of your way to get the attention of these people.  If you don’t ask, you’ll never know if something more than the working application is required.  Most of the time you will find that something more is needed.  Rarely will you find that nothing but the application is included on the deliverable list.

The kicker for me is the fact that some shops are caught up in the mentality that creating documents will solve all the future problems.  You have to strike a balance.  If you’re building software for a client and they say that they want the application, plus specs, plus disaster recovery, what makes it okay for you to create API documentation and charge them for it?  You are, after all, only supposed to be delivering three things.  Arbitrarily adding on other items to the deliverable list, and ultimately passing on the cost of doing so, is not a good way to treat your client.

Another thing to think about is why you’re creating any deliverable.  Sometimes the client may think it’s needed, but when you sit and look at it you can see that the deliverable is never going to be looked at after it is handed over.  In that case you also have the responsibility to point this out to the client and ensure that their money is being used to create new business functionality in the application or documentation that actually is useful.

Personally, I lean heavily on YAGNI (You Ain’t Gonna Need It) when it comes to this stuff.  I’ve spent too many long days working on the latest version of some model or diagram only to see it float off into oblivion, never to be seen again.  It’s frustrating, demoralizing and a complete waste of money that could be spent delivering actual business value.  For me it’s like writing code.  If it’s not being asked for now, and there’s no immediate need for it, don’t code it.  Only do what you need to when you need to.  Now, that said, some deliverables are really bloody hard to create after the fact.  Keep that in mind too.