How to write a Requirements Specification (or how to specify what you want)

	Professional Database Developers
Aldex Software Ltd.

Introduction

This document is intended to help you to write the Terms of Reference under which you want a simple database development to be undertaken.

It only covers general development terms. When putting work out to tender you will also require a Functional Specification (see our Specification page for details).

The sample clauses on this page, which are shown in italics, may be taken and used for the purpose of creating a contract or Terms of Reference relating to a simple bespoke Access development work; larger SQL Server systems may require a more complex treatment.

Please note that we are not lawyers and that any such extracts should be checked by your own legal advisors before being used in a legally binding contract.

General
The purpose of these Terms of Reference is try and ensure that the finished database system is properly designed to accepted industry standards and that it follows best practice methodology. Not only should this give you a better product (more robust, less likelihood of bugs, easier to use, better performance, better scalability, higher quality) but it will also ensure that any future maintenance or enhancements to the system can be undertaken with the minimum of cost and time, whether this is just an extra query/report written in-house or a full-scale update to the functionality.

Terms of Reference
It is usually worth starting out with a general paragraph stating that the work is to be carried out in accordance with recognised industry standards. The most widely accepted standards are those espoused in the Access Developer's Handbook (so far we do not know of one for SQL Server) so you could use a statement such as:

All software is to be developed using industry standard 'best practice' Access methodology - broadly as described by Getz, Litwin and Gilbert in the Access 97 Developer's Handbook published by Sybex, ISBN 0-7821-1941-7."

You will then want to include something that describes the general database design principles to be followed. This is fairly elementary stuff but it is surprising how many databases are NOT designed properly.

"The database will be designed according to the relational model and will usually be normalised to the Third Normal Form. Any deviation from the Third Normal Form is to be undertaken for a specific purpose, such as performance, and is to be documented."

The database system will be split into separate front (code) and back (data) end and will include attachment checking and re-attachment procedures."

Now some description of how you want the naming to be undertaken. Again the industry standard is to use the Leszynski/Reddick naming convention (or a derivation of this). At the same time you should also specify that names should be derived from a restricted 'core' set which allows for future compatibility with other systems (for example most back-end server databases do not accept spaces in the middle of names).

"Naming of variables, forms, tables, etc. will broadly follow the Leszynski/Reddick convention. eg all tables to start with 'tbl', all forms with frm, all queries with qry, all integer variables to start with 'int', etc. unless further modified by a prefix for Scope or Lifetime. For example sintCounter refers to a static integer variable called Counter."

" All names will consist exclusively of the characters a-z, A-Z, 0-9 and the underscore ( _ ). All punctuation marks and spaces are prohibited. Names will use the 'Camel Caps' formatting method."

Then for some general descriptions about how the code/forms should be written.

"Code will be commented, indented and laid out in a logical, readable manner."

"All variables will be explicitly declared. The 'Option Explicit' statement is mandatory in all declaration sections. All declarations will occur at the top of the relevant procedure."

"All procedures will include a dedicated error processing routine."

"All processing should be undertaken using VB (Visyal Basic), VBA (Visual Basic for Applications) or T-SQL (Transact SQL). Macro's should not generally be used."

"All controls buttons to include ToolTip text (where available)."

"All critical data should be validated during data entry."

And finally a more controversial pair of clauses that may cause major problems with some potential developers. However if they won't agree to these then you are leaving yourself dangerously exposed. You won't be able to tell whether or not they have complied with your Terms of Reference and, even more critically, you will be wholly reliant upon their continued existence (and good will) to undertake any future changes to the system, which is usually a very uncomfortable situation to find yourself in. The possible compromise, but only if you really can't find a developer willing to agree to these conditions, is to use an Escrow agreement. Under this the source code is held by a trusted third party (eg a lawyer) and is released to the client if the developer is unable to undertake future development work at a reasonable cost and within a reasonable timescale. NB It is reasonable that a developer may wish to protect certain, defined functions that have been developed previously. If so make sure that these are defined and understood before development commences. The latter of the two clauses is to protect you if the developer going bankrupt or is run over by the proverbial bus.

"Full source code will be included with the system together with a description of how to access it. The only exception to this may be specified existing functions which have been developed prior to, or outside of, this project. Any such functions must be clearly defined, their purpose described and their interface clearly defined."

"If the project is to last for more than 3 months then interim deliveries should be made at approximately monthly intervals."

Conclusion
This document is not exhaustive but is should give you a good starting point for specifying the terms under which you expect Access development work to be undertaken. You may also find it useful when discussing your project with potential developers to make sure that they actually understand all of these terms and can demonstrate to you that they have followed them in previous projects (ask them to show you another project that they have recently completed and ask them to both explain and show you how it complies with these terms).

Finally....
If you have any comments or suggestions, or if there is something that you would like to discuss, then please contact us.

Return to front page