Mime-Version: 1.0
Message-Id: <p0433010bb5d2b0c12e43@[193.112.141.252]>
Date: Wed, 30 Aug 2000 14:11:42 +0100
To: Perforce Defect Tracking Integration Project staff <p4dti-staff@ravenbrook.com>
From: Richard Brooksby <rb@ravenbrook.com>
Subject: Design document structure
Content-Type: text/plain; charset="us-ascii" ; format="flowed"

These are notes from our meeting today.

The design documents should be kept fairly flat in the master/design 
directory.  Avoid false hierarchies which restrict the scope of the 
documents themselves.  Design documents should range across whatever 
they need to, and should slice the "design space" in many different 
ways.

   architecture: the architectural overview, how it all fits together, 
block diagrams, etc.  After reading this, one should basically know 
how it works.

   python-teamtrack-interface: How Python interfaces to TeamTrack.

   python-perforce-interface: How Python interfaces to Perforce.

In general, the design explains how the implementation meets the 
requirements.  So that's how we decide what we need to say.

For example, the big three areas:

   1. data consistency, new queries, etc.

   2. driving from the Perforce interface

   3. driving from the defect tracker's interface

Other topics:

   - file association

   - changelist association

   - replication: how's it done, how it knows what to do, how it 
notices inconsistencies, etc.

   - design for the administrator: installation and configuration

   - design for extensibility to new defect trackers

   - use-case based design references

   - multiple servers

   - platform issues

   - the defect tracker abstraction

We shouldn't be too ambitious, but this is roughly how I imagine it 
breaking down.