This is meant to grow into a firm spec for our project lifecycle. The documents are meant to
The initial contact is hard to control. The request is likeley to be in the form of an email or telephone conversation. However it does make clear who the initial PanEris contact person is, and who the customer contact person is.
When there is a committment from the Partner to procede with the project, or at least read the proposal, then the project node should be created. Before a project can be created the Partner must have an entry in both the Partners Node and details entered in the PM system.
The project node should house all of the following documents, except where the Quality Plan explicitly excludes them from the project.
The Quality Plan is used to document any deviations from this document.
The document should mention personnel involved and their roles in this project.
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, or uses the telephone.
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
What classes of user are going to interact with the system.
Services
What services the system will offer Users. 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); security issues;
anything else?
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?
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:
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 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, anything else?).
Generally important issues
Security; performance.
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.
The Developers.
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.
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.
When the project is complete (or at key stages?) 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
The aim of this document is to identify (of course) things that could be improved, and also areas where we have unusual strengths.
Document Dated: Thu Mar 25 20:02:46 1999 by TimP
Modify this document
Previous Version
