Group:
hypertext
Group:
requirement specification
Topic:
design languages
Topic:
CADES structural modeling with holons
Topic:
Cleanroom software development
Topic:
decision table
Topic:
design errors
Topic:
formal methods and languages
Topic:
object-oriented design
Topic:
requirement specification by assertion
Topic:
software documentation
Topic:
software management
Topic:
software review
Topic:
the 'uses' hierarchy for organizing systems
| |
Summary
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 
| 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
| Quote: visually inspect every bit of analysis and code; most errors are obvious [»roycWW8_1970]
|
Subtopic: requirements documentation
| 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
| 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
| 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
| Quote: the CADES indices for documentation and source files are very important [»pratGD9_1976]
|
Subtopic: tabular definition
| 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
| 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
| 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
| Quote: a true test of self-documenting design is whether its maintainability is maintained [»weinGM_1982]
|
Subtopic: generated design
| 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
| 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
| 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
| 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
[»joneTC4_1979b]
|
Related Topics
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)
|
