Managing Web Projects #6 – The Technical Requirements Specification

We’ve all been in this situation; you’ve pulled off three all-nighters in a row to get your project finished by the delivery date, you’ve worked all weekend and first thing Monday morning you stroll into the office ready to roll it out to live.

Ring ring….

“Hello?”… The client’s on the ‘phone.

“Hi, I’ve just been reviewing the site on the staging server and I think we need to add… blah… blah… blah…”

Your eyes glaze over as you crumple sobbing into a small ball on the floor.

Recommended: Agile Everywhere

Agile. The word evokes images of a racecar zipping around a hairpin turn or a dancer executing a perfect pirouette. It’s sleek, fast, and responsive. At work, being agile can supply you with the perfect response to that tricky sales question or keep you one step ahead of your micromanaging...

Read Article »

How did that happen? There was never a Technical Requirements specification for the project so you’re now stuck in a never-ending cycle of endless rewrites, updates and moving goal posts.

I’ve been there, done that and got the t-shirt. Even so, why should I write a Technical Requirements Specification?

The Technical Requirements Specification (TRS – Also known as a Functional Requirements Specification) scopes out all aspects of the project, from what platforms the website will run on, whether users have to have cookies enabled, down to databases, site and database architecture and testing methods.

Basically, anything that’s not in the TRS isn’t in the web project.

This allows you to turn around to the client and say “Hang on a minute, you signed the TRS off and agreed the users would need JavaScript enabled. Now you tell me 90% of visitors won’t? Sure I can change it but I’ll need a change order, it’ll take x days and cost you x pounds”.

The advantages of this are:

• a) You don’t do unnecessary work outside the scope of the project
• b) You know what you have to design and build for
• c) If anything needs to be changed it’ll cost the client
• d) As they’ll have to pay for the changes, the client may decided not to go ahead or put it off for a while with a “Wait   and see if it crops up” attitude.

What you’re doing is covering your back so that change requests don’t start creeping in at the last minute and you end up building a CMS driven site when it was supposed to be 2 pages of static HTML.

Okay, I’m sold. Sounds a bit long-winded and difficult though…

Well, that depends on the website. Some sites I’ve worked on have had a 2 page TRS simply stating browser platforms, form fields and that JavaScript had to be turned on, others have had 300 pages detailing server security measures, database fields, expected user-input data etc.

The rule of thumb is the more complicated the site, the more complicated the TRS as you’ll need to cover a lot more aspects in-depth in order to cover all of the bases.

It also depends on the company; Joe Bloggs 1 man band probably won’t be too interested and will just sign it anyway but a Fortune 500 company will want to see exactly what they’re getting and how it will work written down in exact detail and then change it (and change it, and change it) until they get what they think they want.

Sounds sensible, what do I put in it then?

In this section I’ll list all of the specifications I’ve used in the past, with examples. This will cover all levels of websites so feel free to pick and choose those most relevant to you. However, note those with a star next to them as these are the ones I feel are fundamental parts of the TRS

1. TRS Version Number *
   This may sound trivial but when you’ve been through 30 revisions and the client says, “Oh, that bit in version 6 about the widget is missing” at least you know which document they’re talking about.
2. Purpose of the site *What will it do? Who is it’s target audience? What’s the aim of the site?
3. Browser Compatibility *
   What browsers does the site have to work on? This is quite important if you’re building a DHTML/Ajaxy/CSS site as different browsers render this type of code differently. You also need to state what browser version you will be designing for. There’s no use putting in a load of flashy stuff that’ll only work in I.E 6 if all the users are still on I.E 5 (and in big corporations no doubt there are people still on I.E 4.5 – scary I know!). There are so many browsers out there to consider but here are the one’s I’d suggest you’d keep as the base-line:
   • Internet Explorer 6 +
   • Firefox 1.5 +
   • Opera 8 +
   • Netscape 6 +
   • Safari 2 + ¹
   • Camino 1 + ¹

   ¹ – Note that these really only need to be considered if you’re designing for a Mac Platform also (which for a website you would be but for an intranet that may not be an issue)

4. Operating system Platforms *
   Different OSs do different things with code (thanks Microsoft), also different companies use different platforms (often weird or old ones), which is important to consider if you’re developing an Intranet. Here are the main ones I’d consider:
   • Windows 98, 2000, NT, XP
   • Mac OS 9, 10
   • Linux (what ever flavours you fancy or just generic)

   Here you should also note minimum screen resolutions that the site will be designed to e.g. 1024×768

5. Browser Requirements *
   Lots of sites can fail on this, not only won’t they work on Firefox (as an example) I *have* to have JavaScript enabled just to navigate, or download a Java Applet or Flash which I may not be able to do. So here, set out what the end-user (i.e. website visitor) needs to have running or installed on their machine in order for the website to work properly. Here are some examples:
   • JavaScript enabled
   • Cookies enabled
   • Flash Plug-in (and version if necessary) installed
   • Java Run Time Environment installed
6. Site Breakdown *
   This section lists each of the main areas of the site and the pages associated with them. There are many ways to present this but I prefer to do it visually using a site map.Here, you would also list common (or “standard” if you prefer) page elements such as:
   • Logo
   • Copyright Notice
   • Navigation
   • Search Box…
7. Section Breakdown *
   Here you list each section in turn, the pages within the section, their components and functionality. Below is a brief example:

   Section Title:	Homepage
   Page Components:	Standard Page Elements Mailing List Form
   Content:	Welcome text to be supplied by client
   Images	– 3 to be supplied by client – 1 sourced from istock photo (code number, cost here)
   Mailing list signup form:	Routes to mypagehere.asp
   Mailing List Form Fields:	First name Surname Email address
   Required fields:	All
   Validation:	Email address must be validated before form is submitted All fields must be filled in
   Data Storage:	Database name, table name

   You would then repeat this process for all pages and sub pages of the site. This means the client is aware of:

   a) Content required from them
   b) How the site will work and interlink
   c) What the functionality is
   d) What information can/is being captured and where it’s going

   This information is also useful for the developer(s) as they then know exactly what each section/page is doing and how any data is being processed without having to second guess what the salesman/project manager/client actually wants.

8. Databases and structureThis is definitely needed if you are using a database. This section outlines the type of database(s), tables within the database(s), field names, field types and lengths. For example:
   

   Database Name:	CustomerDB
   Tables:
   TBLCustomers	CustomerID autonumber ()
   	Name Text (255)
   	Address1 Text (255)
   	Address2 Text (255)
   	LiveOnSite int (1)
   TBLOrders	OrderID autonumber()
   	CustomerID number ()
   	OrderDetails Memo ()

The example above is based around a simple Access database (note that items with no length associated use the field’s default lengths.

Here you could also mention where the data comes from, for example:
TBLCustomers –    /register.asp
/admin/addcustomer.asp

1. Testing *
   Firstly set out what browser platforms/operating systems you will be testing on (this should ideally match the requirements set out in sections 3,4 and 5). In the testing section you’d list all pages and the requirements you are testing against. If this is quite a large section you may wish to move it to a separate document and reference it here.
   For example:
   Page: Homepage (index.asp)
   Testing: Navigation – links go to correct pages
   Mailing List Signup

   – Prompt for Name
   – Prompt for email
   – Invalid email address
   – Incorrect data – ” ‘ % * (i.e. anything that may “break” the database)
   – Data added to database in correct table/format
   – Form routes to correct page

   Design

   – All elements present on page (no broken images)
   – Fits the stated screen resolution?
   – Scales (if applicable) when screen resolution changed)

   Etc. You’d then repeat this process for all pages and on all the platforms required. It’s important to have a good bug-tracking system. This can be paper or pc based but it should be easy for the tester to note problems, and the developer to note the solutions.

   Once this stage is completed the site can move to client testing. It is up to them how they wish to test the site, and depending on the client, how rigorous they will be. Some will simply check a couple of links work; others with try to tear it to bits (and hopefully be frustrated thanks to the testing you’ve done).

   Again, a bug/issue tracking system is important here, to enable the client to log problems.

   Recommended: Risks To Avoid When Managing A Big Project

   

   There are so many ways that we can be overwhelmed with projects: the people we need to manage, the tasks that need to be completed and budget, they can all mount up and become unmanageable. Here we look at a few tips on how to keep those big projects in...

   Read Article »

   If the issue they come up with is something that isn’t mentioned in the TRS and is therefore out of the scope of the project, this will have to be negotiated. Make sure the client pays for it!

2. Server details
   It may not be necessary to inform the client of the location of some servers and their passwords, but having the details all in one place makes for a handy reference tool.You may also wish to list server platforms, processors, hard drive space, ram etc. here if the project warrants it.
3. Backup System
   Details of how, where and when any data will be backed up, who is responsible for the backups (e.g. an external supplier) and data protection notes would go here.
4. Revisions List
   This is useful to keep track of changes to the TRS, when they were made and who made them
5. Client Sign-off
   This is where you and the client sign the document to show that you’re both happy with the TRS and the site’s functionality/components.

Other things that you may consider putting into your TRS can include:

• Deliverable dates/milestones/phases (may also be set out in the contract)
• Definitions of terms used (abbreviations, acronyms etc.)
• Documentation to be provided (help file text etc.)
• Location of work (e.g. your office, onsite at the client office)
• Expected costs (stock photos, travel etc.) (May also be set out in the contract)
  Budget breakdown (may also be set out in the contract)
• Style Guide (if this is a large section, it may be better as a separate document)

Once everyone is happy with the TRS, you’re almost ready to begin work on the actual site but first you need to consider staff, which I’ll cover in the next post.

Don’t forget to check out the e-book version and download your free sample chapter!

About The Author

Katy is always trying to be more productive one day at a time! Whether it's analogue, digital, motivational or psychological who'll try any system that will help her get things done and get organised. As well as running FlippingHeck.com, she also loves making music and reviewing things.

• Follow Katy Whitton on:
• 
• 
• 
• 
• 
• 
• 
•