Here is the requirements and specifications document for review:

caBIG_Requirements_and_Specification_Template.doc (117K)

JimHarrison's comments

These comments were originally sent to Arumani and are included here for discussion purposes.

Summary: There are a number of problems with this template in organization, terminology and grammar. If its purpose is to support new projects, I'd recommend splitting it into separate Requirements and Specifications documents, re-writing the descriptions of the sections (see comments below) and giving more attention to the documentation of use cases, database architectural description (which is missing in the template) and UML diagramming. For documentation of existing projects, I'd recommend using the architectural description outline recommended in the User Documentation White Paper (DocumentationWhitePaper) instead of this, which I think is better organized and does a better job of integrating use cases and UML diagrams into the specification.

Specific comments:

1. There is substantial overlap between the specifications section of this document and the architectural description document proposed in the User Documentation white paper (DocumentationWhitePaper). The two documents serve different purposes--the specs provide a guide to writing software, while the architectural description describes existing software. However, one would expect in a successful project that the specs document should translate directly to the Arch. Descr. document. As an aid to developers, the structure and content of these documents should be reconciled so that they are as similar as possible.
2. Are the Requirements and Specifications best presented as one or two documents? In my experience, requirements are developed by users or through a collaboration between users and developers. The specs are written by the developers once the requirements are complete. If this document will be used in that sort of workflow, how will it be indicated that the requirements are complete if the overall document is substantially incomplete? Additionally, will the document be unwieldy in length? It's 15 pages now just as a template.
3. There is no author or source indicated for this template. It appears that the parts of the template were taken from pre-existing documents. There should be an indication of what the template is derived from and who wrote it.
4. There should also be places in the template for author or source. If there is an approval date in the document change record, there should also be an indication of who approved it.
5. The second page of the distributed document indicates that the second objective of the document "is to describe the design of the requirements." I'm not sure what this means and there are many places later in the template when the word "requirements" is used when I think what is being discussed is the software that is written to satisfy a requirement. Perhaps this terminology is accepted jargon, but I believe it's confusing.
6. On the same page, bracketed italic text is indicated to be used both for required text that is to be replaced and the headings of optional sections. I think this is confusing and these different types of document components should be distinguished.
7. There is no section for references/citations in the table of contents. I think an optional citation list would be appropriate. Note that references/citations are different from what is listed in Section 1.2 Reference Documents.
8. In the Introduction (section 1), I'm not sure that the Scope section (1.1) provides anything beyond what is in the System Overview and Document Overview sections. Why not have an introductory paragraph, then Identification, System Overview and Document Overview as sections 1.1, 1.2 and 1.3?
9. In section 1.1.3 Document Overview there is a reference to "requirements procedural instructions." Does this refer to the steps in the workflows associated with the requirements or existing, pre-software SOPs? It would seem that it would be premature to mention the SOP for workflows supported by software that doesn't exist yet.
10. Section 1.1.3 Document Overview omits reference to the System Architecture and Components sections of the document.
11. I think the descriptions of sections 2.1 to 2.3 need to be edited and expanded.
12. Specifying software qualification procedures in section 2.5 prior to discussing either the requirements (section 3) or the software (sections 4 and 5) seems to me to be premature.
13. The examples given for 2.6 Assumptions and Dependencies seem to be constraints rather than assumptions or dependencies.
14. I think the explanatory text for section 3 Requirements needs to be clearer and should provide additional guidelines about structuring the section. In the tables, "Requirement type" seems to be undefined and it's not clear what should go in the "trace" column. "CCR number" is also undefined and if this represents DoD central contractor numbers, I don't think we need it.
15. The use of terminology in the sections 4 and 5, System Architecture and Components, needs to be improved. In many places, "requirements" is used when I think the reference is to software (for example, "requirement behavior in response to each input" or "actions the requirement will perform"). Also, "software units" are defined in System Architecture as being distinct from code modules or data structures, but the term "software unit" is used frequently in the Components section, apparently to refer to specific code modules. This terminology needs to be cleaned up and clarified.
16. In section 4 under System Architecture Overview, it is recommended that design related to critical requirements be discussed separately. However, there is no recommendation in the Requirements section that critical requirements be identified as such.
17. The subtopics under section 4 System Architecture should be numbered like the rest of the document.
18. Section 5 Components (first para) indicates that databases will be described in appendix C, but appendix C is not defined elsewhere in the document and is not in the table of contents. There are also reference to a Database Design in sections 4 and 5, but there is no specification for how this reference should be constructed, what it should contain and where it should be placed in the document.
19. The subsection numbers mentioned in the third paragraph of section 5 are incorrect (should be 5 rather than 3).
20. Subtopics of application components (5.1) should be numbered and the subtopic descriptions need to be clarified.
21. I'm not sure that the text after the processing subheading (p. 11) makes sense. Some of these items are so specific that reproducing the code (which would not exist at the time of requirements writing) would seem to be required to describe them.
22. A System Security description at the network, database and application level may not be appropriate in a discussion of individual software components (p. 11).
23. Although use cases are mentioned a few times in the template, there doesn't seem to be an organized approach to use cases in this template. I think that's a weakness.
24. Similar considerations apply for UML diagrams. While diagrams are suggested at several points, there is no specification of appropriate diagram types.

There are also a number of typos and grammatical errors that should be cleaned up.