+1 949-420-1972

Specifications

Why is a Project Specification So Important?

Project specifications are an essential part of any web site. A project specification is a lot like a blueprint for building a home. It is a plan created in writing that should be uniformly understandable by all people involved in the project. You wouldn’t build a home without a blueprint would you? Of course you wouldn’t. So why would you build a web site without a plan?

What Can I Expect in a Project Specification?

All or most of the following are typically included in a project specification:

Version Control

Project specifications are subject to change. Each version of the specification is noted at the beginning of the document and each footer of each page contains the document date, document title and version number. That way you can be assured that everyone has the right copy of the document.

A typical version control table will look something like the following:

Version Date Author Description
1.0 04/01/2013 Mark Warrick First Draft
1.1 04/08/2013 Mark Warrick Included revisions per 04/07/2013 meeting. See Appendix “A” for meeting notes.

Distribution List

This is simply a list of all people that will receive the document. It is important for the development team to know who all has received this document and that the people in receipt of the document do not pass it to anyone else without notifying the development team. For example, the development team shouldn’t be getting calls from the CEO of the client company, whom they’ve never spoken with, asking them why his picture wasn’t replaced with more a recent photo.

Client Signature Page

Whenever a new version of the application is introduced, the development team must obtain permission to proceed according to the plan. Therefore, whenever a new version of the specification is created, the client must sign it. That way there will be no questions later on as to what work was authorized by the client.

Responsibilities

Not all the responsibilities lie with the development team! Clients are equally involved in web projects and need to provide content, participate in testing, and sign off on key elements of the project. All the roles and responsibilities of the project should be explained in this section of the spec.

Specification Contents

This is simply an index of the entire document organized in typical contract numbering style. (1.0 Section One, 1.1 Sub Section of Section One, 1.1.1 Sub Section of Sub Section One, etc.)

Introduction

This part of the document is sort of like the prelude to a book. It summarizes the objective of the document and who should be reading it.

Project Objectives

The client should be able to summarize their objectives in a paragraph or two of text. This brief summary will probably also turn out to be the basis of marketing the site.

Success Criteria

The client should define their success criteria. For example, some tangible criteria could be to drive traffic to the site, to increase online sales, or to increase the number of return visits. All these criteria are measurable. Some criteria are much harder to measure, such as to increase brand awareness, to improve customer service, and to gain an advantage over competition.

Site Map

The site map is a visual tool used to represent the site as a whole. In web application development, it is common for a single “page” to consist of many sub templates, but this map does not to have that level of detail, and in fact, most clients wouldn’t understand they underlying technical aspects anyway, so anything technical should be avoided in the site map. Commonly the site map is created with a flowchart tool such as Visio.

Functional Specification

The functional specification is one of the most important parts of the project specifications. In laymen’s terms, it describes the user experience. For example, when the user first arrives at the web site, what do they see? The functional specification should follow the site map and describe every “page” within the system, but again, this is not the place for technical jargon. Keep it simple and make sure the client and development team both understand what needs to be displayed.

Technical Specification

The technical specification is the part of the spec that will be most useful to the actual development team. The first part of this section looks almost identical to the functional specification, but in this section, all the technical details are added in. A programmer should be able to read this part of the document and know exactly what to do without further clarification from the client. If the document is not clear at this point to the development team, then the project manager needs to futher clarify this part of the document by interacting with the client and development team until everyone understands what needs to be done. The technical architecture (for example, the directory structure) is specified here. Security measures are described in detail. Server and browser specifications are defined. Database schemas would appear in this part of the document, and so on.

Content Plan

This part of the specification describes who will be providing what content for which parts of the web site. For example, a client will generally be responsible for supplying company backgrounder information and the development team would likely be responsible for locating and hooking up news feeds from 3rd parties into the site. All of the content issues should be worked out before development begins because otherwise the technical specifications will be wrong and ultimately there may be some significant changes necessary to the overall architecture later in development. Misunderstandings in this area will lead to delays in launching the site and could possibly cause a total project failure.

Marketing Initiatives

How do you suppose people are going to find the site? Will they find it in a search engine? How about in a magazine, on TV, or on the radio? How much traffic do you expect? Do you want to know how the visitors found you, who they are, and what they are doing? All these questions and many more need to be answered before development begins. And this part of the spec is crucial for the same reason that the Content Plan is crucial. Imagine what would happen to your business if you actually had a million customers hitting the site per day because your marketing efforts worked out so well. Would the technical architecture of the site be able to support them? Probably not unless you’ve planned for it.

Testing Plan

The testing plan is created after the final version of the project specification and is made up of the user experience and technical aspects of the system. Clients are equally as responsible for testing the system as the developers are. The testing plan should take into account all functionality of the system. A user should be able to read this document and follow it through the web site. When they encounter a problem, there should be a communication system in place and a procedure for notifying the development team and such problems need to be categorized by importance. It is also very important that different kinds of testers be used. Some of the testers will be focused on look and feel. Others may have some technical experience in their backgrounds and would be more adept at “breaking” the system than others. Ultimately, the development team itself will tend to avoid common mistakes because that is a natural human condition. So, it is always best to test the system with a fresh set of eyes.

Site Updates and Maintenance

This part of the document is related to the Responsibilities section of the document, but it goes into much greater detail. For example, it may have already been defined that the client is responsible for providing all text content for the site, but does that mean that they have to hire on a webmaster to add on new content? Or would it be via web-based forms? Who will monitor the system to make sure that the database remains optimized, that undeliverable email is taken care of appropriately, and that bad records are purged? Who gets called when an error appears on the web site? Who will take over development on the site after the initial development team is done?

Critical Path

The critical path consists of things like milestones, deadlines, and possibly and MS Project File. This section of the site relates to the responsibilities section but goes into more detail. For example, if another agency is being used for graphics, then what is the date at which the programmers working on functionality will have to stop work if they have not received the graphics? This part of the document is especially critical when your web site is time-sensitive. It wouldn’t make a whole lot of sense to release a New Year’s Eve party site in February, now would it? An escalation procedure should also be described here. For example, if the development team is not finished with section “x” of the site by “x date” then the next team of developers from some other company are ready to step in and take over. Always anticipate the unexpected and be ready with a back up plan!

Budget

Some clients request more information about the budget than others. Some clients want to know exactly how each minute of billable time was spent and others only want to see a summary on invoices. Whatever the case may be, the project manager needs to diplomatically discuss the various costs of the parts of the web site and provide as much detail as necessary (within reason) to keep the client happy. Some common line items for budgets will be hourly rates for the various people involved in the project, estimates for each “module” of the site, hosting costs, software costs, hardware costs, and all other costs such as legal fees, copyright fees, advertising expenses, etc. It is not uncommon for a client to have their bottom line budgets cut halfway through a project. With that in mind, the client should be able to make an educated decision about what to cut from development in case they suddenly don’t have all the money they expected they would have. For example, the client may place more importance upon getting a site up with static content vs. a half-completed database project. It is also important that the development team understand what financial arrangements that the client has available to them. For example, if the project manager knows beforehand that the client’s budget is dependent upon how well a certain stock does in the market, then project manager can monitor that stock, coordinate labor accordingly, and know when to expect payment delays.

Appendix

The appendix will include any sort of documentation that supports this spec and any other critical information that should be considered into the project. Some typical appendix items are described next.

    Meeting Notes

    As obvious as this may seem, most people fail to take notes during meetings and forget everything that they discussed within a week of the meeting. Do yourself a favor – take notes. When the meeting is over, go back to your desk and write up your notes. Then circulate your notes with the other developers on the team and with the client to be sure that everyone heard the same thing. The project manager should compile all the various versions of the story into one final story and make sure that everyone involved agrees with that final story. This may involve getting a signature from all the attendees, so keep that in mind. Most importantly, make sure everyone is on the same page and then include those notes into the project specification.

    Development Team Credentials

    This part of the document may include resumes of the development team, case studies of the development company, etc. It is useful to the client and everyone involved in the project to know what experiences the team as a whole brings to the table.

    Design Concepts

    This part of the specification will likely include graphical mockups of the overall design concept of the site. There may be many iterations of the design concept. Whatever the case may be, all those concepts should be printed out and included in the document here. And by the way, never forget that the web users have printers and will share printed versions of the site with other people!

    Prototyping

    Prototyping is a common occurrence in the market today. Considering that many web sites are funded from venture capital and that those investors want to see a “proof of concept” before they’ll invest substantial capital, this part of the document is especially important. For example, it is not uncommon to build the fully-functional prototype with a rapid application development environment like ColdFusion, with the thought in mind that the final system will be rebuilt with a structured platform like Java. Also, the scale of a prototype is likely going to be a lot different than the final product. For example, a prototype might work great for demos, but would never be able to handle the anticipated traffic.

    Assumptions

    You’ve made a lot of assumptions while creating this document. Make sure you list your sources of that information here.

    Glossary of Terms

    Run the final project specification through a spell checker, such as the one built into Microsoft Word. If the spell checker didn’t understand it, your client probably won’t either. So tally up all the words that the spell checker didn’t understand and define them here. For example, it is unlikely that a Client will know what ODBC stands for. So be kind and define it in laymen’s terms here.

    Methodology

    When programmers reach a certain level experience, they start to realize the importance of methodologies. In ColdFusion development, the Fusebox standards (http://www.fusebox.org) are frequently used as the basis for application development. Many development companies have defined their own standards. Whatever your methodology is, be sure to explain it here and make sure that your development team understands how you want the project created.

    Risk Management

    As discussed earlier in this document, you should be anticipating problems and have a backup plan in place to address those problems. For example, what happens if your entire development staff comes down with the flu mid-project? What would happen if the site was not completed by the deadline? What if the project was completed, but the performance was horrible? You need to ask yourself all these questions and many more upfront and be prepared. You also need to know what problems can be placed on hold and which are “mission critical”. I cannot stress the importance of doing this. You don’t want to end up in court, or worse yet, out of business because you didn’t plan for the unexpected.

    Change Control Policies

    You could theoretically refine a project specification for years and never get an hour of work done. There is a limit, usually defined by the client’s deadlines, to how many times you’ll be able to refine this document. Most of the time, a client will ask you to start working before this document is even completed. Try to avoid early starts. If you honestly believe that something critical is missing from the spec, then express that fact to the client and make sure you’ve got something to backup your theory – otherwise the client is going to walk across town the the next development team who may or may not care about that “critical” element. ALL projects have changes. So have a system in place whereby you can accept the change request from the client, prioritize it, and handle the requests. You also need to make sure that while you’re collecting these change requests that you’re comparing them to the project specs. Some changes will be totally out of scope. Your client needs to understand that it takes time to evaluate a change request vs. the agreed upon specifications. And they also need to understand that every change request needs to be reflected in the project specs! Some changes will be critical elements, like, change the DNS entry of the server to our new domain name NOW! Others can be put on hold for a while, like, “move this graphic over 10 pixels”. It is very helpful to have an application already written before starting the project which allows the client to communicate with the development team via an issues tracker of some sort.

    Intellectual Property Agreement

    Is this a work-for-hire agreement? Who owns the code? Who owns the content? Who owns the data? Make sure you work this out BEFORE you and your client end up in court trying to settle a copyright dispute. The internet market moves very fast. If your development team gets an injunction against your web site because they have convinced a judge that the code is being used without their permission, the delays in launching your site could put you out of business entirely.

    Terms and Conditions

    The terms and conditions will likely be specified in another document, however it wouldn’t hurt at all to put them here instead. Terms and conditions are anything that development team and client have agreed upon, for example, the payment terms, termination clauses, etc.