The merits of documenting what you’re going to do before you do it are myriad, and I’m not going to preach to the choir on that topic. What this article is going to focus on is how to structure your document, and what content should be included so that you provide as much value to the business users as possible without overloading the document with technical “jibber-jabber” that will prevent others from reading it.

Elements of Success

I’ve been writing functional specs for over 15 years now, and the most successful ones have the following traits:

  • Clear – Use as much layman terminology as possible.
  • Concise – Do not confuse the customer with long, technical treatises detailing every aspect of the application.
  • Provides lots of pretty pictures – Humans are visual creatures. Providing even simple wireframes is essential for your customers to visualize what you are documenting.

Essential Information

Business Purpose

You must provide a concise section on what the business purpose of the application. This serves two purposes:

  1. Provides a common understanding of the goal of the project
  2. Helps keep the scope constrained

There should be no technical terms, diagrams, geek speak, or technology-related information. From your interviews with your customer(s), you should clearly explain the end result of the project will be.

Benefits

In this section, you should briefly explain how this project will help them solve a specific business problem, how it will make them money, or improve a process. This will be documentation of the information provided to your from your customer. During your interviews, you will hear what the customer expects to gain from the project.

Specification of Deliverable

This is where you go hog wild with your technical implementation plans. You need to break this section down into sub-section related to each specific functional area of the project. In each section, provide a screenshot or wireframe showing how the UI is planned on being implemented. Detail what information will, and will not, be shown on each screen. Explain how the user can expect to interact with the information on the screen.

Resource and Time Estimate

Fairly self-explanatory. Ensure that you break this down to match each functional section that you have in your deliverable documentation. Do not provide a lump sum, because breaking it down will allow your customer see how the project will progress and how long before he/she can expect to see new demos of the project.

Additional Information

Desired Technical Process

If the project calls for a new technical process to be in place in additional to the actual application UI, you need to document it in this specification as well. This section, in contrast to most others, should be very technical and detailed.

Examples could be new backup procedures, hardware interaction, or process workflow.

Current Technical Process

If the technical process is replacing an existing one, clearly explain the current process so that your customer can easily understand the benefits of the new one.

Outstanding Questions

As you are authoring your specification, you rarely get all the information you need at the moment of the first revision. Provide a section where you can list any questions, or missing information, that still need to be resolved. Remember, a specification is a living document and is only set in stone once everyone signs it.

Planned Technology

Sometimes you have a customer that is looking for guidance on what technologies should be used to implement the project. If you are introducing new technologies or languages to your customer’s environment, provide some summary information in a separate section.

More Reading

Specification documents can be small – as little as 4 or 5 pages – or they can be huge. It all depends on the scope of depth of the project.

Here are some more articles that you can read to help you when creating a specification.