Functional vs. design in documentation

People often confuse the purpose and role of functional specifications and design documents. Design and function should never meet in a document. Design and function must be documented during the product development cycle, but their documentation has different purposes and different audiences.

This article discusses the differences between functional and design documentation and the needs of their respective audiences plus the common misconceptions that hamper the development of functional and design documents.

Functional specifications 101
Functional documentation, such as functional specifications documents, is created after sign-off on the requirements document. This documentation defines the “means to the method” of the application.

Functional specifications ensure a systematic approach to the development of a new product or service. Such documentation helps in the following ways:

Enables a more accurate estimate of resources and time necessary to complete a development project

Provides each stakeholder with a singular vision/description of how the product under development is supposed to function

Functional specifications documents sometimes depend on the chosen development methodology (if any) of a development group. Some typical industry standard sections of a functional specification document include:

Business case justifying why the application is being developed to meet customer requirements.

Specifications on the features of the application documenting how the application being developed meets customer requirements.

Mock-ups of the application’s user interface.

Functional specification audience
Functional specifications have the widest audience because they document how the product features are actually supposed to work for the customer. This information in turn feeds activities and programs that other groups across the organization need to perform to ensure a successful launch of the product.

Outside the development team and QA, this information is invaluable during a product launch to many groups including marketing, sales, and customer care.

Nancyfaye Autenzio, president of Mobellium (a messaging software startup company) states, “This type of documentation is appropriate when dealing with technology partners and system integrators where we are pitching strategic alliances, joint development, or integration with other applications and systems.”

Customer care and technical support groups are also a major consumer of functional documentation; they use it to educate their support teams on how the application is supposed to work so they can prepare to support customers after the product launches. They need to know how the product may affect their support infrastructure and the customers they support over the phone and online. Customer care often serves as a “voice of the customer.”

Design documents 101
Design documentation may never see the light beyond the programming team and QA in some organizations. However, it sometimes has beneficial purposes outside of development and quality assurance.

Design documents include information about the programmatic design of the application under development. This design information has limited usage but is necessary to document the intellectual property owned by an organization. Some uses of design documents include documentation of intellectual property developed by a company to substantiate the value of their products during mergers, acquisitions, buyouts, and strategic partnerships between companies.

Such a document also helps maintain the corporate technical knowledge base during both good and bad economic times; organizations with good design documentation aren’t forced to rely on the “oral history of a project” as told by one developer.

Design documentation audience
Audiences consult design documentation for the following information:

Details of application architecture and design goals

Data validation

Documentation of the code (high level)

Data flow diagrams

“Design docs can also become sales and marketing weapons. I have actually seen design docs used to convince industry analysts that a product that was in development should receive a higher ranking in a key analyst report than a number of products that were already installed and in use by customers,” says Kevin Hoisington, a marketing and alliances consultant working in the wireless applications industry.

Misconceptions between functional and design documentation
The roots of the confusion between functional and design documentation are many and varied. General inexperience as well as a lack of strong product management, project management, and technical documentation can pollute the true purpose of these documents. In addition, organizations transitioning from a freer-flowing “shoot from the hip” development environment can have missteps with documentation as they work to implement processes and metrics in their application development process.

Inexperienced staff in the wrong professional roles is a common issue that feeds the misconceptions about the appropriate role of functional specifications and design documentation. Functional and design documentation needs ownership and a place of its own in the software development cycle. Inexperienced staff can have multiple reasons to combine the documents, including:

“Nobody reads these documents. I’ll just get a document out so people don’t complain.”

There is no time to write both a functional specification and design document.

Making the time to create both functional and design specification will pay off in the future as multiple groups rely on the documentation to get their jobs done.