Requirements Specification Sign Off

The customer signs off the requirements specification.

The requirements spec is updated as often as possible during the project if the joint idea or understanding of the customer requirements changes. The requirements spec of any nontrivial project must certainly be made true after it has finished, because it is an important means of understanding the project for future maintainers, and because it keeps the customer on-message.

Functional spec

This says how the thing will actually seem to its users and owners. It tries to consider things in the broad because we are offering solutions---software being nowadays, well, free.

Authors

The Functional Spec will have shared authorship between the Project Leader and the Developers, but inital draft is written by the Project Leader.

Sections

• Service roadmaps

  Each service afforded by the system is mapped out in several ways:

  • what is on each screen and how they link: a skeleton, like Oyster did for Iglu
  • how the users of the service are meant to experience it: what they have to do to access it, and ``traces'' of typical (and rare but important) sessions, explained from the point of view of users' motivations
  • how the users know how to use the service---e.g. we could train them
  • how using the service changes the state of the system

  Naturally `user' here means both `user' (who is typically the customer's customer) or `administrator' (typically the customer's employee); and it refers heavily back to the requirements spec.

• Management

  Things which cannot really be considered as services offered by the software, but which are essential to the running of the system---paying the ISP to keep hosting it, backing it up.

• Customer Data

  If the project relies upon existing data or text then the exact form of that data must be specified. This specification to include, but not be limited to:

  • File naming conventions
  • OS used to create data
  • Delivery medium
  • Delivery timing
  • Data proving/parsing mechanism

Each part of the spec is designated ``deliverable exactly as is'', ``deliverable in some form yet to be decided, in consultation with the customer'', ``deliverable in whatever form seems appropriate off our own bat'', or ``not deliverable---future work''.

Readership

• The customer should feel confident that they will get want they want, and that they know who will be able to use their system, how it will feel, who they need to train, how they will have to support it.
• The project leader should feel happy about taking responsibility for leading the design of the system, including costing.
• The developers should feel informed about the way the system as a whole fits together.
• the future maintainers should be able to understand the way the system as a whole fits together.

Functional Specification Signoff

The customer signs off the functional spec. They are encouraged to play with the skeleton and do some role-play to see how the different services work.

From here on they can't ask us to change what we are doing unless there is an obvious bug in it. Furthermore it is made clear that in the case of the ``to be decided in consultation'' items, we have the last word on how they look. So is this their last chance to insist on anything.

If they don't seem totally happy and clear about what we are proposing, they are encouraged to get us to do it in phases, with meetings before each phase to sign off the additional functionality, or make a prototype.

Architecture document

This says what we think is involved in implementing the requirements spec, and how it should be naturally ``carved at the joints''.

Authors

The developers.

Sections

• Global data structure and format

  Most applications involve data in some way or other---even static web pages have content that needs to be managed. Database systems will obviously demand a data dictionary.

• Data access

  Interface to the data repository from the code. This is a special case of a ``pervasive library'' (below) which is often particularly pervasive and easy to get wrong.

• Pervasive libraries

  These are the libraries we identify as underpinning large parts of the project; the litmus test is ``Will I have to change vast amounts of other code if I change this?''. The plan is that we do these first.

• Pervasive graphic designs

  Similarly, we need to think if there are design issues, or actual designs, which must be pinned down early on.

• Packages

  A carving of the non-pervasive parts of the system into independent parts so as (1) to minimise the ``surface'' area of interface between them and (2) to make each piece doable by one or at most two developers---I take it that we are never going to do a project in which we have to make further subdivisions in order to achieve this. The interfaces offered by each package are made concrete, as are its dependencies on other packages/libraries.

  Graphic designs are treated as packages too; the way they must relate to each other and to the code is pinned down as far as that is possible (consistency of look, space usage).

• Generally important issues

  Security; performance.

Readership

• The project leader should at least be confident that the developers are confident that the architecture is correct.
• The developers should buy into the architecture as at least one of them should have written it :)
• The future maintainers should be able to understand the way the system as a whole fits together.

Implementation plan

This says what order we are going to do things, the timetable, and who is going to do them; it will also contain notes about the development environment etc.

Authors

The developers.

Sections

• Approach

  This section details the overall approach to the project including whether there are separate phases to the implementation and the OS/Database/Middleware which will be used.

• Task Breakdown

  The chunks identified in the architecture document are turned into bite-sized tasks, as are external necessities such as obtaining data or putting up a server---including actions required from the customer. A list of deliverables for each task should be included.

• Timetable

  When are each of these tasks to be done? What are the dependancies? Is there a way of timetabling so as to build in fallback possibilities?

• Resources

  What manpower is required? Designers? Programmers?

• Risk analysis

  Where the unexpected problems are likely to crop up, their likely consequences, and contingency plans.

Readership

• The project leader should at least be confident that the developers believe the timescales are achievable.
• The developers should understand what they are being asked to do.
• The customer is welcome to peruse the plan but isn't required to---except that their attention is drawn to any tasks assigned, as it were, to them.

Acceptance Test

This says what we are going to do to show that we have finished. The document should follow the structure of the Functional Spec very closely, indeed is usually derived from it. On the web individual URLs can be coded directly into the document, so making the Acceptance Spec and the Acceptance Test the same document. It would be very easy and nice to have the results and the sign-off recorded.

Authors

The Project Leader, though on a big system the developers may write specific module tests.

Sections

• The tests or demonstations of the functionality, in same order as Functional spec
• Customers Sign Off

Readership

• The project leader should write and run the tests.
• The developers should run the tests (and so record the testing).
• The customer should run the tests at Sign Off.

Postmortem

When the project is complete we consider amongst ourselves how we feel things went, and if possible elicit a brief impression from the customer of what sort of ``product'' quality they feel they got from us, with specific reference to

• understanding the customer's needs
• communicating effectively with the customer and with ourselves
• meeting the spec
• costing accurately
• achieving value for money: did both the customer and Paneris ultimately feel the project was worth doing at the price?
• effectiveness of whatever technology was used: what worked, what caused trouble

The aim of this document is to identify (of course) things that could be improved, and also areas where we have unusual strengths.

Authors

• The project leader coordinates,
• but developers have free input and
• the customer feedback is quoted verbatim and analysed.

Readership

• The whole Paneris Community can learn from each project review.
• The existence of the review is drawn to the attention of the customer in case they are interested.
• Potential customers can read all the reviews (plus tasty customer comments/awards we put up as headline ``testimonials''). If we decide that a project went badly, we make sure the review explains ``our side of the story'', rather than simply hiding it away.

Document Dated: Fri Mar 26 2:39:48 1999 by TimP
Modify this document
Previous Version