Tuesday, June 29, 2010

A Sample Specification Template

This was created in response to this Stack Overflow question. Apologies for the formatting, it was done in a bit of a hurry and I’ve not had a chance to tidy it up yet.

Specification Template Overview

<General Note:  Optional sections are just that, however for things such as reporting and interfaces rather than excluding it completely you may wish to include it and simply state “No requirement exists in this area” to avoid the ambiguity that absence can create.>

Background and Business Overview (optional section)

<Outline the background to the problem being adressed including details of business process being automated / altered by the solution being discussed.

This may be in the form of text description, flow or swim diagrams or any other appropriate mechanism.  It should be in business English readable by anyone with a basic understanding of the organistation and industry.

Where possible the process description should be separated from the technology and proposed solution.

The aim here is to encourage people to state the underlying issue they are trying to address rather than just talk about a potential solution they may have come up.  This ensures that the solution is based on the genuine requirement and has not (if at all possible) included incorrect assumptions about what is possible / easy or whatever.>

Functional Requirements (mandatory section)

<This is the core of the specification, outlining in detail what the application should do in clear business English.

It may include Actors and Use Cases (or MSF Scenarios and Personas) and partial or complete logical object models to show attributes and relationships between entities.

For websites and applications site maps or navigation layouts may be useful and for both websites and applications screenshots (or rough layouts) will potentially be included for some or all screens.

Where relevant detailed specific data fields being used/recorded should be included, along with details of any calculations of business logic which has to be used.

Remember that the specification needs to be read, understood and agreed by the Senior User so all functional requirements should be clear and unambiguous to the intended audience.  This may influence how you choose to present requirements (for instance logical object models are not easily ready by everyone).>

Reporting (optional section)

<What requirements exist for reporting?  If people have put information into a system they are likely to want to get it out at some point.

Generally where reporting requirements exist the Reporting Specification Template should be used to detail them.  There that is not appropriate it should be used as a guide to the things which may need to be included.>

Interfaces (optional section)

<What interfaces exist to other systems?

What data is being transferred?  Is the link one way or multi-directional (for instance does it just pass payment information to the finance system or does it pass payment information and then receive receipts for payments)?

What format is the data transferred in?  XML, CSV, direct link to a database or a web service?  Is the format some sort of recognised standard?  If so what (and what version)?

How frequently is data transferred?  Live, hourly, daily, weekly, monthly?  How is it triggered – automatically, on a scheduled basis or manually by a user?

Is any data checking required before or after transferring the data?  Or pre or post processing of the data (e.g. after an import all reporting totals should be updated)?

It is unlikely that a full technical specification should be included in this document, however there should be enough information for the programmer to move quickly to building that.  Where specifications exist (for instance where 3rd party standards are involved) references should ideally be included?>

Non-Functional Requirements (mandatory section)

<Non-functional requirements are specific criteria the system must meet which do not relate precisely to what it does, instead focusing on measures and mechanisms which may apply to a system as a whole.

The following areas should be considered when analysing and recording functional requirements:

Performance – Are there limits on how quickly certain actions need to be carried out (for instance is it going to be used by someone with a customer waiting on the other end of the phone)?

Accessibility – Where are users going to access the system from?  Just the office over a LAN or does it need to be accessible via the WAN?  What impact does this have on performance and security?

Security – Who can see/do what?  Is security at an action level (e.g. only person x can run a report) or a data level (e.g. anyone can run the report but the report can only show the data for their team)?  How will security be managed?  Does data need to be stored in an encrypted form?

Data Volumes/Scalability – How many records/transactions/users does the system need to support?  How will this grow over time?  Do records need to be kept for ever or can they be deleted (or archived) after a period of time?

Archive – Is there a need to archive data (potentially resulting from data volume or performance constraints)?  If so what data and how often?  Will it ever need to be restored?  Will it need to be reported on?  How long will it need to be kept for?

Availability – What level of downtime is acceptable?  What level is realistic and likely to be supported by the budget/business case?  Is there a difference between acceptable downtime during office hours and out of office hours?  What possibility might exist for scheduling downtime?

Audit (including logging) – Do transactions need to be audited (that is changes to data recorded and old values kept along with details of who changed them and when)?  If so is it everything or just a subset?  How long does data need to be kept for?  How does this relate to the data volume requirement?  Will this have an impact on performance?  How should it be queried?     

Legislative – Are there any legislative requirements which must be met?  Does certain data need to be auditable or secured in a particular way? 

 For each of these areas (and any others which are relevant), one of three approaches can be taken to the recording of non-functional requirements:

 1)   A specific requirement exists and has been stated by the user.


In this case it should be recorded, however it should also be questioned to ensure it is a genuine requirement. 

For instance users will often demand 100% availability (that is no down time at all, 24 x 7) without really understanding what that means or the likely cost implications.

2)    No specific requirement exists but it is clear that the factor is likely to be significant. 

Performance is a good example here.  While users may say that performance is not an issue (for instance when it comes to how long a report takes to run), it is clear that certain things would be unacceptable (for instance a daily report which took 48 hours to produce).  Where this is the case an assumption should be agreed with the user and recorded.

3)    Genuinely no requirement exists for a given area. 

For instance Archiving – many systems genuinely have no requirement for archiving.  In these instances it should be specifically agreed and recorded that no requirement exists.>

Operational Support (optional section)

<Operational Support covers the tasks which need to be carried out to ensure the continued smooth running of the application.  This can include technical tasks such as back-ups, but also things like maintaining static / sluggish data (data which changes only rarely but does change – for instance updating a list of public holidays as non-working days).

 In many cases these tasks will be short, easy and infrequent so are handled by developers as it’s easier for a developer to write 5 minutes worth of SQL once a year than write a UI to carry out the same task, however in some cases these tasks extend and become a burden.

 The aim of this section is to ensure that, where relevant, such tasks are documented and assessed to understand how they are going to be carried out, by whom and when.>

Constraints (optional section)

<Are there any additional constraints on the functionality or solution?  Is it dependent on another project which needs to be finished before it can work?  Does it need to work to a particular 3rd party standard?  Are there any limitations on the technical solution which can be implemented?  Are there any deadlines which must be hit which may impact the solution?>

Out of Scope (mandatory section)

<During discussions and analysis a number of possible features, functions and elements will come up which are either discounted or put on hold awaiting a future release.

It’s not uncommon for different people coming away from the discussions to be left with different views on whether things have been included or not (frequently thinking that purely the discussion has been postponed and that the feature will still be included).

To avoid this where there are things which have been discussed, or might be thought to be included, which are not going to be, it is best to list them stating them as out of scope of the current release.>

Assumptions (mandatory section)

<Similarly during discussions things are often left hanging or to be confirmed.  In many cases no solid answer can be established (often because no-one wants to take responsibility for making a call on it).

Where this happens the best course of action is to make an assumption and state it as such.  This gives you a solid list of things which need to be finally confirmed and if they can not be confirmed within the necessary timescales then the assumptions can be agreed along with the specification as a basis for proceeding.>

Glossary (optional section)

<List (in alphabetical order) details of any acronyms, and technical or business terms which are either not in common usage among the document audience or may be ambiguous.>

 Version History (mandatory section)

Date

Version Number

Made By

Comments

<Date of change>

<New version number – including whether Draft>

<Name of the person making the change>

<Brief details of the change being made and what prompted it>