Topic: design documentation

topics > computer science > programming > Group: program design

requirement specification

design languages
CADES structural modeling with holons
Cleanroom software development
decision table
design errors
formal methods and languages
object-oriented design
requirement specification by assertion
software documentation
software management
software review
the 'uses' hierarchy for organizing systems


A program design is recorded, if at all, in notes, formal specifications, minutes of meetings, blackboard diagrams, design documents, and program comments. Design documentation is used to make choices between competing proposals, communicate those choices to programmers, and to assist with understanding a program prior to modifications. Perhaps the most important document is the system architecture, modulo diagram, or uses hierarchy that breaks a large project into manageable chunks.

Parnas has developed design documentation that breaks a complex problem into many independent 'displays' with decision tables. Hypertext is useful for informal documentation. Flow diagrams are often used for high-level documentation.

In a large system, the design documentation may itself be overwhelming. In many systems, the design documentation is not maintained and soon becomes out-of-date with the code. For these reasons, design documentation should be part of the code itself --in small enough pieces that it can be reviewed before all modifications. (cbb 4/98)

Subtopic: importance of documentation up

Quote: management of software requires a lot of documentation; need a 1500 page software specifications vs. a 30 page hardware specification [»roycWW8_1970]
Quote: write down interface and management decisions; otherwise designers may be "90% complete" for months [»roycWW8_1970]
Quote: until coding begins documentation, specification, and design are the same; if the documentation is bad the design is bad [»roycWW8_1970]
Quote: software maintenance requires good documentation [»roycWW8_1970]

Subtopic: design review up

Quote: visually inspect every bit of analysis and code; most errors are obvious [»roycWW8_1970]

Subtopic: requirements documentation up

Quote: organize a requirements document as a reference document instead of an introductory narrative; worth the expense; easy lookup [»parnDL2_1986]
Quote: in manufacturing a succession of blueprints, drawings and specifications capture the relevant requirements [»rossDT1_1977a]
Quote: describe objects in terms of the module that creates them
Quote: a requirements document includes the host specification, interface specifications, a specification for each output value, timing and accuracy constraints, likely changes, and undesired event handling [»parnDL2_1986]
Quote: Larch shared and interface languages for incremental construction of readable specifications from other specifications; includes theorem prover for semantic checking [»guttJV9_1985]

Subtopic: top-level design up

Quote: a module guide states the design decisions that will be encapsulated by each module [»parnDL2_1986]
Quote: divide design documentation into requirements, testing, resources, processes, and module design, decomposition, dependency and interfaces [»hestSD10_1981]
Quote: the hard part of programming is constructing the interlocking concepts that make a software entity [»brooFP_1986]
Quote: design a document by stating the questions, one per section; then write the document by answering the questions [»parnDL2_1986]
Quote: designers should design the data processing modes, data base, execution time allocations, interfaces, processing modes, input/output processing, and operating procedures [»roycWW8_1970]
Quote: designers should produce an overview document that is understandable, informative, current
Quote: define one and only one place for every fact
Quote: the decomposition phase of the review process should be communicated by the designer; the reviewer should not need to derive the decomposition [»parnDL12_1994]
Quote: the design of the 'uses' hierarchy should be a major design milestone [»parnDL5_1978]

Subtopic: record design alternatives, notes up

Quote: a module design document records the major design decisions for design reviews and documentation [»parnDL2_1986]
Quote: when designing a system should record every decision, minimize dependencies between decisions, and record shared decisions [»silvBA_1981]
Quote: include all design alternatives in the documentation along with why they were considered and why they were rejected [»parnDL2_1986]
Quote: designers need help in keeping track of notes and recalling them appropriately; requires understanding of the design process and the problem [»soloE5_1984]
Quote: since the consequence of design is in the future, forecasting ought to be part of design; but forecasting can be dismal [»simoHA_1981]
Quote: Hypertext useful for structuring documents and notes used during system development [»conkJ12_1987]
Quote: ZOG used to manage the ZOG project; contained all documents, software, reports, schedules, etc. [»mccrDL10_1984]

Subtopic: tie source to design up

Quote: the CADES indices for documentation and source files are very important [»pratGD9_1976]

Subtopic: tabular definition up

Quote: use tables of mathematical expressions for practical, precise definitions; each cell defines a specific case [»parnDL8_1984]
Quote: use tables to specify the post-value of a variable for various combinations of pre-values [»parnDL12_1994]
Quote: an 'NC' entry specifies that the variable is not changed for that combination of pre-values

Subtopic: define each function up

Quote: document program by displays that specify the program's function and specify the function of omitted sub-programs; short enough to understand [»parnDL5_1988]
Quote: a display is a 1-2 page document with a specification, a program, and all referenced specifications [»parnDL12_1994]
Quote: use a lexicon to define terms, functions, constants, and types that are used in multiple displays [»parnDL12_1994]

Subtopic: data vs. process up

Quote: system designers like data flow diagrams for communication and system documentation; easy to construct [»bansJP4_1993]
Quote: both data (state-boxes) and process (clear-boxes) views are needed for designing software; related by box structures [»cobbRH11_1990]

Subtopic: self-documenting up

Quote: a true test of self-documenting design is whether its maintainability is maintained [»weinGM_1982]

Subtopic: generated design up

Quote: the VFSM simulator generates message sequence charts showing states, inputs, outputs, and communications; with seqflow, it documents the behavior of a module [»florAR1_1997]

Subtopic: documentation flaws up

Quote: in documentation, avoid stream of consciousness (write as think) and stream of execution (write as it happened); difficult to find information [»parnDL2_1986]

Subtopic: problem of change up

Quote: keep design documents consistent with a system; if multiple versions are required, confine the differences to small modules [»parnDL2_1986]
Quote: use pseudocode in design documentation; keep both versions consistent; use different programmers [»parnDL2_1986]

Subtopic: problem of scale up

Quote: in a large system, the formal specification is too bulky for practical use; instead design work switches to informal communications [»joneTC4_1979]
Quote: as a program increases in size, specifications stop increasing in size because they become too large to write and read [»joneTC4_1979]
Quote: the design for a million line system would take a year to read; too bulky for practical use

Related Topics up

Group: hypertext   (44 topics, 786 quotes)
Group: requirement specification   (11 topics, 307 quotes)

Topic: design languages (12 items)
Topic: CADES structural modeling with holons (24 items)
Topic: Cleanroom software development (38 items)
Topic: decision table (29 items)
Topic: design errors (15 items)
Topic: formal methods and languages (53 items)
Topic: object-oriented design (30 items)
Topic: requirement specification by assertion (28 items)
Topic: software documentation (64 items)
Topic: software management (28 items)
Topic: software review (80 items)
Topic: the 'uses' hierarchy for organizing systems
(18 items)

Updated barberCB 4/05
Copyright © 2002-2008 by C. Bradford Barber. All rights reserved.
Thesa is a trademark of C. Bradford Barber.