You click the submit button. No errors. Check.

Is that all there is to testing? That’s only half the battle. Is there a confirmation step? Should it go to a Thank You page? What should the thank you page say? Does any of the data on the form, such as dates, phone numbers, or other critical information need to be validated for proper format? What fields are required? Are any fields dependent on other fields or saved data?

If a detailed specification document does not exist, how is your QA tester supposed to know the answer to any of these questions? How can you confidently check that form off the list and send it on to your client? It’s one thing to know if something is broken, but it’s entirely different to know how it is supposed to work. That is where most of the headaches come from. Incomplete requirements, too many assumptions, not enough detail.

Why is a specification document important?

How many general contractors start building a house without a blueprint? Why, then, do so many of us build websites without a spec document? Creating a thorough specification document reduces ambiguity and the potential for scope creep later down the line. It will save time during design and coding because your team will have a clear set of instructions and programmers won’t have to guess and fumble through development. It will also save you iterations of going back and forth with the client after the site has been built, trying to get it just the way they wanted it.

So what goes into a specification document? I’m sure there are hundreds of templates and formal methodologies out there. Since every project and client could require a different approach, I’ll share what has worked for me and you can feel free to mold it to your own liking.

What goes into a specification document?

1. Overview
Identify high-level items, such as an overview of the website, the primary goals, any secondary goals, and the target audience. This may be obvious, but it serves as a good reminder to stay focused on what is important. It also forces both you and your client to articulate these items to ensure you’re on the same page from the beginning.

2. Information architecture (site map)
Next, I would do a high level site map. This constitutes your information architecture and how you are going to organize the content of the website. Start by identifying all of the information that needs to be included in the site. Then group logically related information together and determine how it should be labeled and organized so that site visitors may find things easily and quickly.

On a traditional hierarchical site, this could be a simple tree structure with groupings connecting pages and sub-pages. On a site that is more abstract, you might want to do a story board, which could be a simple illustration showing various states and animations that take the user from place to place on the site.

3. Detailed page descriptions
For each page of the site, you should identify all the content, user actions, data and other functionality that will be included on that page. This can include any or all of the following elements depending on what is included on the page: wireframes, data dictionary, and process workflow.

4. Wireframes
A tremendously useful tool on the page description step is the use of wireframes. A wireframe is an illustration or diagram of all the elements that appear on the page. Wireframes should not show any design elements, so the client is focused on the relationship of all the elements on page, not on the color or layout. This is all about the page elelements, not the design. I’ve found that clients often have a hard time with this concept and expect it to show the design, but it’s critical they understand the point of the exercise.

5. Data dictionary
According to the IBM Dictionary of Computing, a data dictionary is a “centralized repository of information about data such as meaning, relationships to other data, origin, usage, and format.” In other words, it’s information about information. Remember, we want to reduce ambiguity, so detail is critical! Ambiguity = headaches. Headaches are bad. These are some items you should identify about every piece of data collected on a form or displayed on a page:

• Field label
• What type of data is is? (ex: text field, checkbox, date, phone number, zip code, 12-hour time, etc.)
• Is there a proper format the data needs to be entered in? (ex: MM-DD-YYYY)
• Is there a minimum or maximum length for the data?
• Is this field required?
• Is there a calculation involved?
• Is this field related to another field?
• Any other restrictions? (ex: If this is a start date, it cannot occur after the end date.)

6. Process work flow
If you have a contact form on a page, what happens when the visitor clicks submit? If visitors can register on the site, how does the registration process go? What happens when a visitor puts an item in their shopping cart? Do visitors need to login before making a purchase, or can they checkout without an account?

This is the piece that is often hardest to articulate. It requires that you understand the process at work and are able to anticipate any actions that the user may want to take at any point in the process. In my opinion, this is where analysts and consultants really earn their money. Making a site user-friendly is not an easy task. After all, look at how many bad sites are out there.

I’ll sum up by saying this, no specification document is going to be perfect and save you from all problems. There are some issues that just can’t be discovered until you or the client start to use the system as it is being built, or even after it is done. However, this is a vital piece of the puzzle to keep everyone accountable and on the same page. In my experience, scope creep is the single biggest project (and at times entire company) killer.

And from my perspective, it’s the single most important piece of the QA process. Without a specification to test against, your QA will only be at the kindergarten level.

About: Brian Cendrowski

After spending 10 years in full-service website development, Brian founded Unmatched Quality, a website testing provider. Unmatched Quality can do the grunt work that you don’t have the time or patience to do. We will kick around a website to verify that all the pieces of the sites work. We can also make sure the site performs well in all the major browsers, test performance so you don’t lose those impatient visitors, and confirm that the site sticks to web standards, which helps ensure your site is accessible to everyone. If you’ve ever been frustrated because your customers continue to find issues with your sites, perhaps we can help. You can contact Brian at 803-319-0784 or brian [at] unmatchedquaility.com.