Additional sections have been added from "Software Functional Specification Template"

This wiki template has placed Brad's notes as right shifted instruction notes. When specification has reached a certain level of maturity, these instructional notes may be removed. It is recommended that each of these sections actually be prepared as children subpages of the main project specification page, and included in this document. This has many benefits:

• the versions for each section can be tracked separately,
• enhances the ability for collaborative viewing and separate editing of the various sections of this document
• allows each section to have its own internal headings and table of contents separate from the main table of contents
• allows all the sections to be aggregated for viewing in this master document.

The appropriate include statements have been inserted in this template. To easily get from this document to each section for editing, each section should begin with a link to its individual page, such as

_This section located at [Project Specification - Introduction]_

Here is a section for Brad's notes on the design of the specification document: Software Design Specification Introduction

• Describe the purpose of this document
• Describe the scope of this document
• Describe this document's intended audience
• Identify the system/product using any applicable names and/or version numbers.
• Provide references for any other pertinent documents such as:
  • Related and/or companion documents
  • Prerequisite documents
  • Documents which provide background and/or context for this document
  • Documents that result from this document (e.g. a test plan or a development plan)
  • Define any important terms, acronyms, or abbreviations
  • Summarize (or give an abstract for) the contents of this document.

• Related software or hardware
• Operating systems
• End-user characteristics
• Possible and/or probable changes in functionality

• Hardware or software environment
• End-user environment
• Availability or volatility of resources
• Standards compliance
• Interoperability requirements
• Interface/protocol requirements
• Data repository and distribution requirements
• Security requirements (or other such regulations)
• Memory and other capacity limitations
• Performance requirements
• Network communications
• Verification and validation requirements (testing)
• Other means of addressing quality goals
• Other requirements described in the requirements specification

• The KISS principle ("Keep it simple stupid!")
• Emphasis on speed versus memory use
• working, looking, or "feeling" like an existing product

For each such goal or guideline, unless it is implicitly obvious, describe the reason for its desirability. Feel free to state and describe each goal in its own subsubsection if you wish.

• Use of a particular type of product (programming language, database, library, etc. ...)
• Reuse of existing software components to implement various parts/features of the system
• Future plans for extending or enhancing the software
• User interface paradigms (or system input and output models)
• Hardware and/or software interface paradigms
• Error detection and recovery
• Memory management policies
• External databases and/or data storage management and persistence
• Distributed data or control over a network
• Generalized approaches to control
• Concurrency and synchronization
• Communication mechanisms
• Management of other resources

Each significant strategy employed should probably be discussed in its own subsection, or (if it is complex enough) in a separate design document (with an appropriate reference here of course). Make sure that when describing a design decision that you also discuss any other significant alternatives that were considered, and your reasons for rejecting them (as well as your reasons for accepting the alternative you finally chose). Sometimes it may be most effective to employ the "pattern format" for describing a strategy.

At the top-most level, describe the major responsibilities that the software must undertake and the various roles that the system (or portions of the system) must play. Describe how the system was broken down into its components/subsystems (identifying each top-level component/subsystem and the roles/responsibilities assigned to it). Describe how the higher-level components collaborate with each other in order to achieve the required results. Don't forget to provide some sort of rationale for choosing this particular decomposition of the system (perhaps discussing other proposed decompositions and why they were rejected). Feel free to make use of design patterns, either in describing parts of the architecture (in pattern format), or for referring to elements of the architecture that employ them.

If there are any diagrams, models, flowcharts, documented scenarios or use-cases of the system behavior and/or structure, they may be included here (unless you feel they are complex enough to merit being placed in the Detailed System Design section). Diagrams that describe a particular component or subsystem should be included within the particular subsection that describes that component or subsystem.

Note:
This section (and its subsections) really applies only to newly developed (or yet-to-be developed) portions of the system. If there are parts of the system that already existed before this development effort began, then you only need to describe the pre-existing parts that the new parts of the system depend upon, and only in enough detail sufficient to describe the relationships and interactions between the old parts and the new parts. Pre-existing parts that are modified or enhanced need to be described only to the extent that is necessary for the reader to gain a sufficient understanding of the nature of the changes that were made.

If any subcomponents are also deemed to merit further discussion, then describe them in a separate subsection of this section (and in a similar fashion). Proceed to go into as many levels/subsections of discussion as needed in order for the reader to gain a high-level understanding of the entire system or subsystem (but remember to leave the gory details for the Detailed System Design section).

If this component is very large and/or complex, you may want to consider documenting its design in a separate document and simply including a reference to it in this section. If this is the option you choose, the design document for this component should have an organizational format that is very similar (if not identical to) this document.

• Choice of which specific product to use (compiler, interpreter, database, library, etc. ...)
• Engineering trade-offs
• Coding guidelines and conventions
• The protocol of one or more subsystems, modules, or subroutines
• The choice of a particular algorithm or programming idiom (or design pattern) to implement portions of the system's functionality
• Plans for ensuring requirements traceability
• Plans for testing the software
• Plans for maintaining the software
• Interfaces for end-users, software, hardware, and communications
• Hierarchical organization of the source code into its physical components (files and directories).
• How to build and/or generate the system's deliverables (how to compile, link, load, etc. ...)

Each particular policy or set of tactics employed should probably be discussed in its own subsection, or (if it is large or complex enough) in a separate design document (with an appropriate reference here of course). Make sure that when describing a design decision that you also discuss any other significant alternatives that were considered, and your reasons for rejecting them (as well as your reasons for accepting the alternative you finally chose). For this reason, it may frequently be convenient to use one of the more popular "pattern formats" to describe a given tactic.

For this particular section, it may become difficult to decide whether a particular policy or set of tactics should be discussed in this section, or in the System Architecture section, or in the Detailed System Design section for the appropriate component. You will have to use your own "best" judgement to decide this. There will usually be some global policies and tactics that should be discussed here, but decisions about interfaces, algorithms, and/or data structures might be more appropriately discussed in the same (sub)section as its corresponding software component in one of these other sections.

Much of the information that appears in this section is not necessarily expected to be kept separate from the source code. In fact, much of the information can be gleaned from the source itself (especially if it is adequately commented). This section should not copy or reproduce information that can be easily obtained from reading the source code (this would be an unwanted and unnecessary duplication of effort and would be very difficult to keep up-to-date). It is recommended that most of this information be contained in the source (with appropriate comments for each component, subsystem, module, and subroutine). Hence, it is expected that this section will largely consist of references to or excerpts of annotated diagrams and source code. Any referenced diagrams or source code excerpts should be provided at any design reviews.