Varsys - Software and Web Development
Common Pitfalls of Dysfunctional Specs

Functional specifications are the last best opportunity for project players to be sure that the development team is about to build the right thing. Don't miss this chance to get it right – the success of the project depends on it.

What's a Functional Specification?

Functional specifications play a vital role in ensuring that all members of a development team know what they're building. Where a requirements document focuses on "what" is required, the functional specs go further to provide the glue between the "what" and the detailed design for developers.

A good functional spec answers, from the customer's perspective, the "how" questions and also, for developers, provides the specifics of what is to be built. It documents how the product is supposed to work, using a combination of text and diagrams that explain desired functionality.

Create Functional Specs

A valuable specs document leaves nothing left to interpretation and stands as an insurance policy to ensure that the client and development team understand all project requirements. To limit project failure, unexpected investment, and customer disappointment during the development process, avoid these common pitfalls:

Pitfall #1: Specs are too vague or incomplete.


For many, this pitfall is the Achilles' heel of the development process. Specs that are left to interpretation have a very high chance of resulting in poor implementation. Developers may fail to implement requirements or execute the requirements incorrectly. Ambiguous specs often result due to a lack of individual capability and skills, and a general lack of understanding. Not everyone understands the technical language and tools being used to write the specs document – many people lack technical training or standard modeling technique. Conversely, individuals that do understand coding often have a poor understanding of the client's business requirements.

Tips for Avoidance

The specs document should be the joint responsibility of the business analyst and system or application designer/developer. A business analyst may lack understanding of coding language or tools well enough to build the specs note alone. It is through the dynamic discussions between the analyst and the developer that:

  • The analysts can feel comfortable that the developer has understood the requirements and reflected them properly in the high-level design.
  • The developer has the opportunity to question the requirements for better understanding and to provide early warnings of requirements that may not be met due to technical constraints or cost.

The focus is on good negotiation and well-informed decisions happening early in the development cycle. The mantra of requirements is to focus on "what" not "how." Spend time up front to clarify the what/how grey area and develop complete and unambiguous functional specs.

Pitfall #2: Using text for non-text specs.


Many authors use text to describe non-text designs. Text uses language to describe specs and can vary based on experience (i.e. very technical). Descriptions left to the interpretation and subjectivity of the reader can easily lead to wrong expectations.

Not all individuals working on a project are trained to know which model or diagram to apply to a specs document. While there is a set of standard IT modeling/diagramming techniques and tools for support, the issue is about leveraging training in modeling/diagramming techniques and having a refined standard set for use within the organization.

Tips for Avoidance

Specs should be put into graphical form rather than text wherever possible. Functional specs that are complemented by visual support (e.g. object models, state-transition diagrams, flow charts, screen shots) significantly reduce subjective interpretation and provide immediate and straightforward understanding. This greatly reduces the time required in walkthrough sessions and leads to better negotiation and agreement prior to development.

Appoint individuals that are trained with using the organization's standard modeling/diagramming techniques. Support them with tools designed to let them do work effectively and efficiently. Get them to work closely with business analysts and developers who have a comprehensive understanding of the client's business and functional requirements.

Pitfall #3: Level of Detail


Agile project approaches challenge traditional methods of development by stressing frequent releases and little or no documentation. Use case modeling has deemphasized the need of functional specs. "Just enough" detail is encouraged to provide developers with enough information and leeway to implement the best engineering strategy possible.

Detail is a common point of dispute for functional specs, especially among agile project approaches.

Tips for Avoidance

The level of detail should be specific to the project at hand in order to manage project risk and complexity. Overall, value derived from functional specs should be in direct proportion to the cost of mistakes and potential failures in meeting requirements.

Bottom Line

Ineffective functional specifications result in wasted time, costly mistakes, and increased development time. Further, they contribute to failures in meeting expectations. Take requirements practices to the next level by avoiding common pitfalls.

For assistance with developing functional specs, please contact Varsys.

Back to Knowledge Center ?/a>