P4DTI Project Design Document Procedure

1. Introduction

This procedure describes how design decisions become design documents in the Perforce Defect Tracking Integration project.

This readership of this document is project staff or anyone extending the project.

This document is not confidential.

2. Procedure

Initially, when the design decision is made, a record of decisions should be created. This is a either

• a document in the "doc" directory like "doc/YYYY-MM-DD/TITLE/" which records the decisions, or
• an e-mail message in the archive.

The latter are much easier to create, but care should be taken to give them enough context that they stand alone as documents, as they are likely to be published and used by future developers.

Then, when the design is implemented, actual design documents should be submitted at the same time as the implementation, in "master/design/". And of course, when the implementation is changed, the design documents should change accordingly.

Often, we'll be able to branch the original design decision document into the maintained design document. It's unlikely that there'll ever be a merge of any sort, but it's good to retain a record of the origin of the text and diagrams.

In any case, design documents should cite the record of the design decision, not just be branched from a design document. An internal record in Perforce isn't really enough. If the whole project were printed out and put in a folder it should still "work".

This procedure ensures that:

1. design documents are current w.r.t. the implementation;
2. we have a referencable permanent record of design decisions.

We should refrain from writing design documents that aren't implemented. If we have design ideas that we could implement, they should be in "doc" as marked as such. We should clearly separate speculation and design plans from actual design documentation.

A. References

B. Document History

Copyright © 2000 Ravenbrook Limited. This document is provided "as is", without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this document. You may make and distribute verbatim copies of this document provided that you do not charge a fee for this document or for its distribution.