This is meant to grow into a firm spec for our project lifecycle. The documents are meant to
The initial proposal is probably freeform, and could be just a brief email, unless it is in fact a first draft of the requirements spec. However it does make clear who the initial Paneris contact person is, and who the customer contact person is.
The Paneris contact meets the customer to get an idea of what it is they are after.
This says what the thing is for. It provides the motivation for everything which is done subsequently. We should be able to justify every piece of work by a chain which ultimately leads back to the "Business need" section of this document.
The first draft is written by the Project Leader. It may be corrected by any member of the team, including the customer, but it reflects the understanding that Paneris has gained of what is required, so even when a document called a Requirement Spec is given to us by the customer an original Paneris document should be created.
Background
So that we all know enough about the customer, circumstances and origin of the project to be `in' and `clued up'. I hate feeling like a mushroom.
Business need
How the project will help the customer make money.
Users and services
What classes of user are going to interact with the system and what services it will offer them. This is still at a fairly high level---for instance, mockups would generally be inappropriate here. It will be grounds for concern if there are not lots of references back to ``Business need''.
Constraints
External factors influencing choice of OS, language, hardware, software;
required performance (roughly);
anything else?
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:
The customer signs off the requirements spec. From here on they must be paying money (if they aren't already).
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.
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.
The Functional Spec will have shared authorship between Project Leader and the Developers, but inital draft is written by the Project Leader.
Service roadmaps
Each service afforded by the system is mapped out in several ways:
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, anything else?
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''.
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 (if that's going to be quicker than just doing the full system, which with web stuff it typically won't be).
This says what we think is involved in implementing the requirements spec, and how it should be naturally ``carved at the joints''.
The Developers.
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. Does this ever happen?
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 a 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, anything else?).
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.
The Project Leader, though on a big system the developers may write specific module tests.
Document Dated: Mon Nov 9 20:04:28 1998
Modify this document
Previous Version