OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita-busdocs message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: RE: [dita-busdocs] structure of specifications

Thank you Bruce.


Rather than posting all the individual references, can you wait and until we put together a literary review so that it can be compiled all in one place? This will make it easy for us to summarize our findings into a coherent whole. It will also allow us to weed out references which we do not feel are relevant to our focus.


Thanks for being so speedy to start tracking down resources though.




From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com]
Sent: Monday, June 21, 2010 3:02 PM
To: dita-busdocs@lists.oasis-open.org
Subject: [dita-busdocs] structure of specifications


Here's a third category, quite a bit more various than the other two. (I'm looking into research in linguistics again, but that will take longer.)


Specification Structure
[Software first, there's much less extant specifically for hardware specs; I put that at the end.]



Software Requirements Specification
Version 1.0 approved
Prepared by <author>
<date created>
Table of Contents ii
Revision History ii
1. Introduction 1
1.1 Purpose 1
1.2 Document Conventions 1
1.3 Intended Audience and Reading Suggestions 1
1.4 Project Scope 1
1.5 References 1
2. Overall Description 2
2.1 Product Perspective 2
2.2 Product Features 2
2.3 User Classes and Characteristics 2
2.4 Operating Environment 2
2.5 Design and Implementation Constraints 2
2.6 User Documentation 2
2.7 Assumptions and Dependencies 3
3. System Features 3
3.1 System Feature 1 3
3.2 System Feature 2 (and so on) 4
4. External Interface Requirements 4
4.1 User Interfaces 4
4.2 Hardware Interfaces 4
4.3 Software Interfaces 4
4.4 Communications Interfaces 4
5. Other Nonfunctional Requirements 5
5.1 Performance Requirements 5
5.2 Safety Requirements 5
5.3 Security Requirements 5
5.4 Software Quality Attributes 5
6. Other Requirements 5
Appendix A: Glossary 5
Appendix B: Analysis Models 6
Appendix C: Issues List 6



Wherever possible, I have tried to provide guidelines (instead of prescribing requirements) for the contents of various sections and subsections of the document. Some may prefer to require more detailed subsections of a particular section, choosing one or more of the subsection topics from the list of guidelines provided. In this sense, this document is really a template for a template.


In devising this template, I have gleaned information from many sources, including various texts on Software Engineering (Pressman, Sommerville, and Van Vliet), Object-Oriented Development (Booch, Rumbaugh, Berard, and Wirfs-Brock), various SEI reports, DoD-Std and Mil-Std documentation requirements (2167/2167A), and IEEE documentation standards (particularly IEEE-1016 for software designs, and IEEE-830 for software requirements). I have made every effort not to assume or impose a particular software development methodology or paradigm, and to place more emphasis on content than on format.


... many parts of the document may be extracted automatically from other sources and/or may be contained in other, smaller documents. ... [need not be] a single document


System Overview
Design Considerations
Assumptions and Dependencies
General Constraints
Goals and Guidelines
Development Methods
Architectural Strategies
strategy-1 name or description
strategy-2 name or description
System Architecture
component-1 name or description
component-2 name or description
Policies and Tactics
policy/tactic-1 name or description
policy/tactic-2 name or description
Detailed System Design
module-1 name or description
module-2 name or description


The above outline is by no means exclusive. A particular numbering scheme is not necessarily required and you are more than welcome to add your own sections or subsections where you feel they are appropriate. In particular you may wish to move the bibliography and glossary to the beginning of the document instead of placing them at the end.


The same template is intended to be used for both high-level design and low-level design. The design document used for high-level design is a "living document" in that it gradually evolves to include low-level design details (although perhaps the "Detailed Design" section may not yet be appropriate at the high-level design phase).



Several standards
organizations (including the IEEE) have identified nine topics
that must be addressed when designing and writing an SRS:


Functional Capabilities
Performance Levels
Data Structures/Elements
Constraints and Limitations


[Detailed examples and citations of Authoritative Sources.]



Software Functional Specification Template



[More templates]
The Volere Requirements Specification Template has been downloaded in excess of 20,000 times. ... Note that academic use is excepted from the payment system. ... The template provides for each of the requirements types appropriate for today's business, scientific and software systems.
[Probably also applies to hardware specs]


This last cites the following:
    IEEE Software Document Definitions
    SQAP - Software Quality Assurance Plan IEEE 730
    SCMP - Software Configuration Management Plan IEEE 828
    STD - Software Test Documentation IEEE 829
    SRS - Software Requirements Specification IEEE 830
    SVVP - Software Validation & Verification Plan IEEE 1012
    SDD - Software Design Description IEEE 1016
    SPMP - Software Project Management Plan IEEE 1058




Hardware Specification Structure





[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]