1.0 Title: Contract Deliverable Item Description (CDID)
2.0 Purpose: A Contract Deliverable Item Description (CDID) is a description of a project “deliverable” or an “artefact” or whatever term indicates that an object has been or will be created through the activities of people and other resources in a “project” in the narrower sense of the word used in business. (i.e. it is implied that somebody contracts for a product and pays to have it created.)
(this is the "Why" of the CDID, or the "Value Proposition")
3.0 Recommended Usage: CDID’s should be used where control of the content and format of documents and other objects such as electronic data and software systems as well as the hardware itself (which might be computers, or a plane, a ship or a building). CDID’s are part of the Data Dictionary for any given project and should be located in the top DD directory.
(this is the "When, Where, Who" of the CDID)
NEW (22/08/16) : In Google Workspace (a.k.a. gSuite and Docs) template documents with predefined format and functions (such as the pm45n "timestamp") can be created and duplicated as empty pre-formatted deliverables called "Copy of <whatever>)" - these need to be partially renamed for use in any project - but keeping the CDID first sequnce label - (example - a new log will be: pm45n <title of some sort> <project number in hri07e format>)
4.0 Frequency: In general CDID's are written once and revised as required. In fact, the hri07e project is setup to write a basic set of SIG's and CDID's so that they do not have to be written at all for individual projects, and if new ones are identified as part of the project, the burden of writing the CDID can be passed back to the SIG (see 6.1).
5.0 Reference Documents:
The concept of the Data Item Description (or DID) is based on US DoD practices around MIL-STD's. They are also evident in the NTIS "Technical Report Documentation Page" Form
5.1
5.2 http://www.ntis.gov/services/submit.aspx SF298
5.4 Sample Tailoring of 2167A DIDS for Software-First Life Cycle
5.5 Frequently Asked Questions about Data Item Descriptions
5.6 https://assist.daps.dla.mil/quicksearch/
ASSIST-Quick Search provides direct access to Defense and Federal specifications and standards available in the official DoD repository, the ASSIST database
5.7 Data item descriptions (wikipedia)
5.8 MIL-STD-963
6.0 Responsibility:
hri07e has two sources for CDID’s
6.1 SIG’s One of the primary tasks of the km6 type of Special Interest Groups (SIG’s) is to define with as much rigour as necessary, the artefacts that would normally be produced by “professional” persons practising the art of the SIG. For engineering several other groups “professional” has a legal status and responsibility – for others it does not. While the responsibility for the production of the CDID is carried by the SIG, its application and content is the responsibility of whatever authority “signs off” on the CDID. If bad things happen and that authority feels they were misguided by the CDID it can be argued that by signing off on it, they were aware of the generalized nature of the document and that they – as the self-proclaimed “professional” – should have noted the error and taken action within the SIG to correct it.
6.2 Projects Each project owner is at liberty to create their own set of CDID’s which apply to that project if they have some reason to do so and they do not have to use the hri07e CDID’s. In that case they have nobody to blame but themselves as they are not only the executor of the CDID but the author, and presumably, the professional authority as well. (It should be noted that the whole purpose of having SIG’s produce CDID’s was to share the knowledge and reduce the cost. Having your own private list of CDID’s does little to achieve that and is very expensive besides.)
7.0 Ownership: CDID’s are copyright by the authoring organization but there is little point in protecting their distribution. They should be distributed as freely as possible.
8.0 Level of Effort (costs)
As there are costs associated with every document produced they should not be called up unless they add value to the project or the corporate knowledge base and capability. Production of a new CDID can be anywhere form 6 or 8 hours for a draft to dozens of hours for committees of people. (The MIL-STD DID’s are written by a few in hours, reviewed by dozens for days and debated by hundreds for weeks.) For most deliverables the effort being estimated is not for writing the CDID – but for the execution of the work required to produce the deliverable. For example: the deliverable defined by MIL-STD-785B Task 102 DI-R-7081 “Reliability Mathematical Model(s)” will probably require 3 to 4 engineering staff from 2 to 5 days per sub-system of 10 to 15 functional elements to create the first draft.
MIL-STD DID’s do not give any indication of the cost associated with producing the deliverable. This section is new for the CDID’s.
9.0 Risks
The consequences of producing a deliverable for a CDID are assumed to be less severe than those of NOT producing the deliverable – and if they are not then the owners would be wise to avoid incurring the costs of adding that deliverable to the scope fo work of the project. Since some safety and environmental tasks may in fact torpedo the whole project and result in all of the funds spent to that point to be wasted – it is understandable that this may be the first choice of some owners. However – the costs of lawsuits and jail time should be weighed against costs of an undesirable result. The authors of the CDID should identify what the probability and severity of possible consequences might be if the work is not performed. As unlikely as it seems - they should probably also identify the risks involved with “successful” completion of the tasks as well.
added:
- The risk that most frequently reifies is actually that of an approved deliverable being called up which in act adds no value to the project. (Usually called for by a self-serving consultant who says "Oh - you need an X" - when in fact 80% of the information contained in X is already being produced elsewhere)
- the second most frequent is that a deliverable is ignored because it costs too much and "the plane crashes". (That is a figure of speech - please do not assume that all deliverables prevent plane crashes - they do not - even if the TV show says they do. "If it only saves one life" is not a license to waste time and money - except in the Nuclear industry)
10.0 CONTENTS:
Many CDID’s exist from various sources (especially MIL-STD’s – where they are called Data Item Descriptions or DID’s ) and can be adopted for use in many projects where the requirements are similar. It is common to hear of DID’s being “tailored” [5.3], [5.4] for each project (in some cases, to the point of being useless) or they can be written from “scratch” if the project domain expert feels they are doing something entirely new and unique and for which no equivalent document exists (in which case it should make a good Phd thesis as well.)
This document is the most obvious example of what the contents are
10.1 Title – a short but informative title (<10 words) <dd:km kc:km3title>
note: Titles are not meant to be thesis titles which attempt to summarize the contents and use every available keyword to assist search engines.
10.1a a.k.a. (also known as)
Alternative names for deliverables almost always exist for common documents
- for example:
A transmittal may (arguably) be referred to as a "cover letter", a "Way Bill", a "Bill of Lading", a "Bill of Materials", a "Packing Slip", a "shipping note", an "insert" and who knows what else. These may or may not be the same thing - but this is the place for the CDID to indicate which ones are in fact the same thing an which ones are not.
10.2 Purpose – <dd:km kc:km3purpose>
Explain the reason for the deliverable and what value it adds to the project. (It should also be noted that the standard document should be the most rigorous example of the deliverable – with the expectation that this is only required in the most compelling of circumstances. For many projects it will be safe to reduce the requirements. If the requirements are insufficient it may be that an entirely different DID should be considered.)
10.3 Usage -<dd:km kc:km3use>
– Explain the circumstances where the deliverable is normally required – and also the circumstances where it is “over-kill” or can safely be reduced in scope.
10.4 Frequency <dd:km kc:km3freq>
– Some deliverables are only done once in a project – other are repeated. It is not always obvious how many times a document may have to be submitted, revised or even completely re-written – as may happen when computer code is “re-factored”. Documents which are repetitive (eg “Progress Reviews”) should have a “standard practice” repeating cycle (eg: a “scrum” is usually held every two weeks) but the Project Manager is free to apply whatever schedule is felt to be optimal.
10.5 Reference Documents <dd:km kc:km3ref>
– Identify the other deliverables associated with this deliverable – both the pre-requisites – and documents that cannot be produced with at least a draft version of this document.
- identify the source documents for the technology and methods used in producing this deliverable.
10.6 Responsibility <dd:km kc:resp>
There are at least two levels of responsibility required for most deliverables:
The “standard document” should be produced by personnel who are experienced and recognized for their expertise in the procedures. This becomes the”gold standard” for that type of procedure.
For a specific project it is the responsibility of the senior technical authority for that project to select and edit the CDID as appropriate for the task at hand.
The concept of deliverable descriptions has a long history (especially in he US military procurement cycle) and there is a almost endless supply of publicly available documentation which can be used as the basis for CIDID’s. While they are a rather mixed bag of quality and usefulness – many of them are nearly complete and have no IP restrictions on their use – but also no liability is accepted for their misuse. (The second paragraph still applies.)
10.7 Ownership <dd:km kc:owner>
It should be clear from the outset who “owns” a given deliverable for a project. Not all deliverables are given in full to the project owner – even if the name implies that they are. (Hence the use of the term “artefact” is preferable – even if no-one knows what it means.) Many consultants will do produce a lot more paper behind the scenes than they put into the report – which only gets the strict limits of the contracts. However – access to that information may be crucial later on (e.g. the calculations for a failed structure) – hence its existence should be identified. (Its non-existence may be an indicator that work was paid for but not actually done.)
10.8 Level of Effort <dd:km kc:loe>
An estimate of the typical tasks, resources (types of skills and equipment) and the hours required should be included in each CDID.
This requirement is unique to this specification; it is not done in MIL-STD DIDs or elsewhere.
10.9 Risks <dd:km kc:risks>
10.10 Contents <dd:km kc:contents>
The contents of each CDID will follow the pattern established in this document - i.e all 12 current headings should be headings included although some of them (eg item 11 Data Typing) are for future development.
For section 10 (this section) each item should also identify the data dictionary and the key code that is associated with that content item in the format <dd:*** kc:*****>
- the dd:*** elemnt should link to the approiate SIG data dictionary .
- the kc:**** elemnt should link to the approriate key code page.
these elemnts should only occur in the titles of the contents section (10.0) of the CDID.
10.11 Data Typing <dd:km kc:km3type>
Every deliverable should be submitted with a Data Sheet that includes all of the key code information relelevent to that sheet - (work order no, CDID, submission date, owner, and the key codes specified as determined by the deliverable - i.e. a "weight report" for a ship would included the current "Gross Tonnage" and "Lightweight" as network accessible values via the data sheet.)
Automated document systems can use these data sheets / transmittal as an initial QC check on the format and contents. (for example - if the person submits a "Weight Report" that has key codes that are not specified in the CDID - say- "Hours worked" - this provides a first check on whether the person has misidentified the document.)
10.12 File Handling Policy <dd:km kc:policy>
11.0 Metadata (Data Typing)
All hri07e cdids will identify their contents (section 10.0 above) by section/paragraph/"chunk" by the relevent data dictionary owner (in this case - SIG:KM) and by the data dicitionary keycode. The infromation will precede eash section heading in the format dd:<SIG> kc:<data dictionary keycode>. The keycodes should be linked to the equivalent entry in the Data Dictionary. In future editions this is intended to become an automated link in XML or some future extension of XML.
12.0 File Handling Policy
Because almost all files will be in electronic format the CDID itself must state how documents of this type must be handled by the information system.
12.1 Backup
Backup policies must be stated for time of retention
12.2 Privacy
PIPEDA (Canada), Sorbanes Oxley (USA) and equivalent privacy handling methods must be specified.
12.2 Security
The security level of the document must be indentified and options noted.
13.0 Procedures
When the contents (section 12.0) are produced by well defined procedures, or alternatives exist for the procedures - these item should be listed and linked as part of the CDID.
NEW CDID's
When a new type of document is required - reserve a number in the appropriate SIG and let the SIGmaster know something's coming - someday. You will not be responsible for creating the SIG CDID - but you should be willing to work with the SIG when they get around to doing it (after sufficient prodding by SIG's KM & QA)
14.0 Tutorials
If training and educational materials are available or required these should be listed and linked as part of the CDD