Design Specifications- What, How, Yet, How Much?

I know we have all been there.  You (or your team member) create a fabulous customization, report, or interface.  Or, at least you think it’s fabulous.  But once it’s delivered to the client, the issues begin…

• -          It doesn’t work the way it we thought it would
• -          We need this additional work for it to meet our needs
• -          We thought we already explained this

And the list goes on and on and on.  I had a webinar last week for GPUG about creating specifications for customizations, reports, and interfaces, and I thought I would share some of that content here as well.  I continually am reminded of the importance of the spec process, it seems like every week.  And if I let it slide, either because I think it’s not a big deal or the client is resistant to committing to a spec document for whatever reason, the universe almost always course corrects me at some point in the project (e.g., budget overrun, client dissatisfaction, etc).

So we all know the reasons to create specs, right?

• -          Reduce risk
• -          Ensure clear communication and expectations
• -          Accurately scope work
• -          Create a better outcome in terms of design and client response

But what are the key components of a successful spec?  Now, I completely understand that this list will vary based on the client, the developer, and the specifics of the customization/report/interface being addressed.  This list simply serves as a starting point checklist of the normal “must-haves”:

• -          WHAT is the spec for? A functional/plain language description of the problem to be solved.   Visual flowcharts/mockups as necessary to make the point.  Include any caveats/assumptions/risks to be clear up front.
• -          HOW do you plan to address the need? The technologies/tools/methods to be used, including prerequisites for deployment.   At a minimum a high level technical design, but could be more detailed including fields, calculations, and needed logic.  Whether it is high-level or detailed depends on what you need to be able to accurately scope it out, and how involved the project may be.  If it is a large project, the initial spec may have a high  level technical design with a statement that a full technical design is included in the estimate and may change. On smaller projects, a full technical design may not take much time and allow you to better scope/estimate the project.
• -          YET, what might be the hurdles? Always note any exceptions, assumptions, or outstanding questions that might impact the estimate and/or complexity of the project. It’s okay to have outstanding items, as long as they are documented and ultimately addressed in the project.
• -          HOW MUCH will this cost?  And don’t just focus on development costs, make sure you include project management, design, testing (unit, function, process, and supporting end user acceptance testing) in your estimate.

I love getting all of this down on paper, I just do.  And it is great when a client fully commits to the process, and we can make sure we are all on the same page before work starts.  But, as with anything in this line of work, you can’t make the perfect the enemy of the adequate at times.  So although a spec is important, don’t let it become the bat with which you bully others (either your team members or the client).  Try to remember the intention of the spec, and approach it with good faith.   Things may change as the project proceeds, and the client may grow in their understanding of their own needs.  Of course, assess the impact of these changes on your budget and timeline, but also know that a minor change with no measurable impact can be addressed without a lot of hub-bub (assuming that the necessary decision makers are aware).

Naturally, everything above is just my opinion.  I would love to hear from you all regarding your “must-have’s” for successful spec documents, and your challenges (and successes) with applying these guidelines to projects.

Christina Phillips is a Microsoft Certified Trainer and Dynamics GP Certified Professional. She is a director with BKD Technologies, providing training, support, and project management services to new and existing Microsoft Dynamics customers. This blog represents her views only, not those of her employer.