In short, a project specification is a detailed outline of the steps needed to complete a development project. Specifications (specs) generally include a project summary defining the objectives, a list of anticipated changes, and the proposed product design. Some might refer to specs as end-user requirements. A well-written specification is an integral part of the software development process. It helps everyone understand how the product is intended to function, what features are necessary, and how users will interact with the product.

Project specifications wear many hats and often mean different things to different people. In some instances, specs are very technical and in other instances, specs contain only high-level details on what a project needs to accomplish. The nature of the specification can vary greatly depending on the organization.

How to create specs

The first step in spec writing is to define the project. Is this an enhancement to an existing feature? Or is it a brand-new feature or process? Who are the stakeholders needed to complete the project? The next step is to think about what is needed to complete the project. This is often the “brainstorming” phase where ideas are discussed and subject matter experts weigh in. Lastly, it’s time for the spec writer to work their magic and get into the nitty-gritty details.

Spec writers must understand the big-picture goal of the project but also pay attention to the details and tasks needed. A thorough analysis of all the areas impacted and potential constraints is necessary. There can be myriad paths to accomplish a project with many scenarios to think through. What appears to be a simple project oftentimes ends up impacting multiple other areas of the software resulting in the spec taking way more time than originally anticipated.

A recent example was a specification to activate Retailer Groups for Credit Card Cash Back (CCCB) programs. Assigning Retailer Groups (specific merchants as defined by the credit union) to a CCCB program allows credit unions to offer better rewards to members using certain local retailers. For this project, the underlying infrastructure for Retailer Groups was complete and the feature was available for selection on the rewards program configuration. You would think that it would be a simple switch to turn on the feature but oh no, here were the changes needed:

• Program calculations
• Program/screen edits
• New Retailer Group lookup
• CCCB Calculation Report
• CCCB Transaction Register Report
• CCCB Payout history screen

The research phase

Determining the above changes involved researching numerous CCCB rewards projects implemented over the last five years (and reviewing multiple iterations of specs associated with the projects). I also reached out to the programmer and a quality control tester assigned to these previous projects for confirmation of the current functionality.

The research phase of the spec writing process can oftentimes be very time-consuming. You must thoroughly understand the product in order to determine what the changes need to be. Research may include running test scenarios, meeting with subject matter experts, and reviewing documentation. You must gather as much background information as possible and ask questions as appropriate.

The ripple effect

Another challenge for product design/spec writing is thinking through the “ripple effect” where what appears to be a simple program change actually touches multiple areas. Also, is there potential for the changes to break current functionality? What if the software is not used as intended?  The spec writer must understand how all the pieces fit together and be able to envision how the software will be used.

I often times think of the spec writer as the “middleman” between the programmer and the end user. The spec writer must understand (at least at a high level) the necessary programming changes but also be able to be able to put themselves in the shoes of the end user.

More than meets the eye

Next time you wonder why a project is taking so long to come to fruition, think about the hours of analysis and research that needed to happen before the project was even assigned for programming!