Project Specifications
Project specifications are an essential part of any web site. With almost
absolute certainty, I can guarantee you that without a spec, your site will
not be successful, and ultimately your business will suffer from a poorly
thought out web application.
Why is a Project Specification So Important?
A project specification is a lot like a blueprint for building a home. It
is a plan created in writing that should be uniformly created and understandable
to 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 |
15/04/2007 |
PT |
First Draft |
| 1.1 |
16/04/2007 |
PT |
Included revisions per 01/12/2007 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 summarise 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 categorised 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 optimised, 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 realise
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, prioritise 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.
