For as long as I can remember, I’ve enjoyed reading.  As I’ve aged the kinds of books that I find interesting have been expanding.   Historical fiction never interested me as a youth, but as an adult I found a number of authors in this genre that I just love.  Patrick O’Brien wrote the popular Aubry-Maturin which follows a British Navy Captain and a Physician.  The books are set right around 1800 during the Napoleonic Wars.

One of the things that I found interesting was the social protocols involved in dining onboard ship.  Among many other intricate expectations, one stood out for me: An invitation to dine with the Captain could not be refused.  Dr. Maturin, the Physician in the series, once tried to decline an invitation because he was deeply involved in his scientific work.  A crew member quickly explained that the nature of the invitation was really more like an command.  Maturin was well aware that formal, written orders must certainly be obeyed or face grave penalties, possibly as severe as execution for treason.  He also knew quite well that direct spoken orders were also not optional in the military service.  How was he to know that an “invitation” to dinner carried quite nearly the same weight as the others by force of tradition, respect, and the Captain’s honor?  Well, he didn’t until one of the crew explained it to him, dragged him down to his cabin, got out a clean coat, and pushed him into the Captain’s cabin just in time for dinner.

So what does this have to do with software development? 

I recently realized that developers, designers, and testers are in much the same position as Dr. Maturin when it comes to requirements.  There are the requirements written in contracts and statements of work, these are like Maturin’s written orders.  They must be met or very bad things happen, possibly as severe as not getting paid and losing any future work from the client.  Direct Orders are like the requirements passed on to the team in formal use cases and requirement documents.  Everyone knows you have to make them happen before you ship a product.

What about suggestions from your project manager?  What about new ideas from the client or other stake holders?  These suggestions can be delivered by email, in a meeting, or (heaven help us all) by voicemail.  They are rarely incorporated into your formal documentation and only in extreme cases will they result in a contract modification.  Still, if you are a developer, designer, or tester you better make sure that these suggestions get into the final product.  If you have been around for a while, you have probably encountered a clients or manager where ignoring their spoken suggestions about your work is far more damaging that missing a minor requirement in the contract. 

The test team can make suggestions too.  A good tester will regularly find all manner of problems that have no specific requirement they are violating.  If the test team and important stake holders decide a problem should be fixed, requirement or not, it’s going to have to be fixed before the build gets approval to go to production.

Ok, enough with the dysfunctional doom and gloom.  This isn’t a bad thing.  We are talking about good ideas that just came a little too late to be written down in the initial requirements for a project. What’s a good way to handle this?  Obviously these suggestions need to get written down somewhere.  The more consistent and accessible the “somewhere” is, the more likely you are to have a good outcome. 

For our NITRC project we have a few layers of documentation for our requirements.  At the highest level you will find a number of bullet points in the contract.  Luckily for us these are general and broad enough that as long as we keep our eyes open we won’t run afoul of them.  Below that, we don’t actually keep the typical MS Word multi-page requirement document for each iteration.  Instead we create a living requirement package made up of the Feature Requests (FRs) that have been bundled together and the use cases which we store in a wiki.  We eat our own dog food, so our FRs are stored in the NITRC system itself in a tracker module.  (The tracker is essentially a bug/ticket system.)  Each FR has a running text commentary that can be supplemented by anyone on the team.  Since our Use Cases are kept in a wiki they can be easily updated as well. 

The key for us is we are accustom to recording all decisions and many discussions in the tracker.  In the planning phase of an iteration we triage new features and bugs with the whole team.  The meeting notes from the triage are taken directly in the tracker so any “suggestions” get written down right there at the same level as the formal requirements we are implementing.  Next, high level analysis and design info is recorded in the tracer for each FR.  Before the actual development starts we quickly review the FRs one more time.  Again, the meeting notes from that review are recorded directly in the tracker and, if necessary, in the Use Case wiki is updated.

The important part of our system is that when the test team puts together their test plan they are not working from a “dead” requirements document.  Instead they pull all their information from the notes in the tracker and the wiki.  That is the final check to make sure that all important suggestions make it into the final release.

I know that this really isn’t anything ground breaking.  Most good teams will have something similar in place to make sure the details don’t get lost.  I think the real insight is making sure that any “invitations to dine with the Captain” are written down where the testers are sure to see them.  From there it is the test team’s job to make sure that everyone gets dressed and arrives on time for the first course.