5

The IEEE 12207.1-1997 guide (Software life cycle processes - life cycle data) has a list of general content requirements for all description documents (section 5.1, page 12). This includes "notation for description" (bullet f). Does this just refer to whatever system or structure is used for the description (e.g., design languages, diagrams, etc.), or is there another meaning?

The standard defines the purpose of a description as "Describe a planned or actual function, design, performance, or process" so it's very high-level. The specific context where I need to apply it is a Software Design Document. We have a customer requirement to use sections of this IEEE standard, as well as another document, and I'm putting together a template that organizes all those requirements into a single document structure.

5

The short answer to your question is, yes, this "notation for description" is stating your your description documents include a design language and sufficient information for a reader to understand that design language. A complete analysis, based on IEEE Std 1016-2009 IEEE Standard for Information Technology--Systems Design--Software Design Descriptions is below.


As of 13 August 2015, the current standard for software design descriptions is IEEE Std 1016-2009 IEEE Standard for Information Technology--Systems Design--Software Design Descriptions. I'm going to be basing the rest of this answer on that document and version.

The definition of a software design description (SDD), as presented in 1016-2009, is:

An SDD is a representation of a software design to be used for recording information and communicating that design information to key design stakeholders.

Unlike previous iterations of 1016, the 2009 release is very supportive of multiple development methodologies. For example, the wording of the 1998 revision was very much inclined toward a Big Design Up Front approach. The ideas in 2009 can be more readily applied to big design up front, iterative and incremental, and even reverse engineering approaches. In addition, it doesn't mandate a format - many older IEEE standards for software engineering are geared toward paper documents. The contents of 1016-2009 can be applied to "paper documents, automated databases, software development tools, or other media".

In 1016-2009, an SDD contains 1 or more design views. Each design view is governed by a design viewpoint, which is framed by one or more design concerns. A design viewpoint also defines one or more design elements, which are expressed in a given design language.

The following are experpts from Section 2 Definitions that apply to these terms:

3.2 design concern: An area of interest with respect to a software design.

3.4 design element: An item occurring in a design view that may be any of the following: design entity, design relationship, design attribute, or design constraint.

3.12 design view: A representation comprised of one or more design elements to address a set of design concerns from a specified design viewpoint.

3.13 design viewpoint: The specification of the elements and conventions available for constructing and using a design view.

All of this means that you start organizing your SDD based on the people who will use the information contained within the SDD. Different stakeholders will have different needs - consider network or system administrators who need to know about distributed components and communication protocols, database administrators who need to know about the data structures for databases to optimize them, quality assurance staff who will be testing the software, engineers implementing and maintaining the software, and so on. Each of these people have different concerns that need to be captured in the SDD. These concerns will be used to frame various viewpoints.

Table 1 in 1016-2009 provides a number of example design viewpoints. It identifies 12 different design viewpoints, but there is no indication that this is a comprehensive list nor is it all necessary for all projects. Some of these viewpoints are a context viewpoint, an information viewpoint, an interaction viewpoint, state dynamics viewpoint, and algorithm viewpoint. For each viewpoint, the table also gives example design concerns. As an example, the information viewpoint is used to address concerns regarding persistent information while the algorithm viewpoint provides procedural logical and the logical viewpoint captures static structure (classes, interfaces) and use of types and implementations (classes, primitive types).

Once you've identified the viewpoints, you define the design elements that are used to demonstrate that viewpoint, using a design language. The design elements that are appropriate depend on the viewpoint. For example, a design elements in a state dynamics viewpoint would be events, states, transitions, activities, triggers, and so forth. In an algorithm viewpoint, the design elements would be attributes, data, and processing steps. In an information viewpoint, the elements would be data types and classes, data storage formats and structures, and access mechanisms.

After defining your design elements, you represent them in a design language. 1016-2009 doesn't require any specific language or notation. They list several examples - the appropriate UML diagram types (if any) are often listed as examples for each viewpoint. However, the standard also mentions flowcharts and pseudocode as examples for the algorithm viewpoints or entity-relation diagrams for the information viewpoint. In a note in Section 4.9 Design Languages, the standard indicates that standardized design languages (IDEF0, IDEF1X, UML, Vienna Definition Language) are better than established languages without a formal definition (state machines, automata, decision tables, Warnier diagrams, Jackson Structured Design, HIPO models). However, the author is free to choose any design language that is appropriate.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.