Precise Documentation: The Key to Better Software

Abstract

The prime cause of the sorry ``state of the art'' in software development is our failure to produce good design documentation. Poor documentation is the cause of many errors and reduces efficiency in every phase of a software product's development and use. Most software developers believe that ``documentation'' refers to a collection of wordy, unstructured, introductory descriptions, thousands of pages that nobody wanted to write and nobody trusts. In contrast, Engineers in more traditional disciplines think of precise blueprints, circuit diagrams, and mathematical specifications of component properties. Software developers do not know how to produce precise documents for software. Software developments also think that documentation is something written after the software has been developed. In other fields of Engineering much of the documentation is written before and during the development. It represents forethought not afterthought. Among the benefits of better documentation would be: easier reuse of old designs, better communication about requirements, more useful design reviews, easier integration of separately written modules, more effective code inspection, more effective testing, and more efficient corrections and improvements. This paper explains how to produce and use precise software documentation and illustrate the methods with several examples.

Full text

Precise Documentation: The Key To Better Software
David Lorge Parnas
Abstract
The prime cause of the sorry “state of the art” in software development is our failure to produce good design
documentation. Poor documentation causes many errors and reduces efficiency in every phase of a software product’s
development and use. Better software documentation methods, and the resulting better documentation, would
revolutionize the software field.
Most software developers, believe that “documentation” refers to a collection of wordy, unstructured, introductory
descriptions occupying thousands of pages; they think of text that nobody wanted to write and nobody trusts. In contrast,
Engineers in more traditional disciplines, think of precise blueprints, circuit diagrams, and mathematical specifications of
component properties; they recognize that documentation is their main design medium. Software developers do not know
how to produce precise documents for software and consider documentation to be an afterthought. In fact, it should
represent forethought not afterthought.
Among the benefits of better documentation would be: easier reuse of old designs, better communication about
requirements, more effective design reviews, easier integration of separately written modules, more effective code
inspection, more effective testing, and and increased efficiency when making corrections and improvements.
This talk explains how developers can produce and use precise software documentation and illustrates the methods with
several examples.
Middle Road Software, Inc.
David Parnas 1/56 Zurich documentation slides.pages
1. ------------Documentation: a perpetually unpopular topic!3
2. ---------------------------Why Real Improvement is Difficult!4
3. ----------Dilbert Knows that documentation is important.!5
4. ---------------------------Programming vs. software design!6
5. -------------------------------What Is Meant by “Document”!7
6. -----------A Preliminary Example: Dell Keyboard Checker!8
7. -----------------------Requirements for Keyboard Checker!9
8. ------------------------------------No Theoretical Advantage!10
9. -----------------------------Completeness and Consistency!11
10. ---------------Are computer programs self-documenting?!12
11. ----------Internal documentation vs. separate documents!13
12. ----------------------------------------Models vs. documents!14
13. -------Design documents vs. introductory documentation!15
14. --------------------Specifications vs. other descriptions (1)!16
15. --------------------Specifications vs. other descriptions (2)!17
16. -----------------------------------------Extracted documents!18
17. -------------------------------Documents Are Not Programs!19
18. -----------Roles played by documents in development - 1!20
19. -----------Roles played by documents in development - 2!21
20. ------------Costs and benefits of software documentation!22
21. ----------The most important software design documents!23
22. ----------------------------Considering readers and writers!24
23. ----------------What makes design documentation good?!25
24. --------------------------------Documents and mathematics!26
25. -------------------------------Requirements Documentation!27
26. The two-variable model for requirements documentation!28
27. --------------------------------------------------------Notation!29
28. ---------------------------------------------Non-Determinism!30
29. ---------------------------------------------------Relation NAT!31
30. --------------------------------------------------Relation REQ!32
31. ------------------Experience and examples: Requirements!33
32. ------------------------------------------------------Interfaces!34
33. -----------------Surprising Observations about Interfaces.!35
34. -----------------Software component interface documents!36
35. ----------------------------TFM for keyboard checking Tool!37
36. ------------------------Equivalent Conventional Expression!38
37. ------------------Extract from Module Interface Document!39
38. --------------------------------Program function documents!40
39. ------------------------Example of Program-Function Table!41
40. ---------------Program-Function for a Poor (real) Program!42
41. -------------------------Module internal design documents!43
42. ---------------------------------Checking an Internal Design!44
43. ----------------------------------------Additional documents!45
44. --------------------Tabular expressions for documentation!46
45. -------------There are many forms of tabular expressions.!47
46. --------------Tables like this Can be Found on the Internet!48
47. -------------------------------------This says the same thing!49
48. ---------------------This Too is A Mathematical Expression!50
49. ------------------------------------------------A Circular Table!51
50. --------------------------------------------The Bottom Lines:!52
51. ----------Management’s Role in Document Driven Design!53
52. -------------------------------------------Research Problems!54
53. ----------------------------------------Summary and Outlook!55
54. ------------------------------------------------------Thank You!56
Middle Road Software, Inc.
David Lorge Parnas 2/56 Zurich documentation slides.pages
Documentation: A Perpetually Unpopular Topic
Software documentation is disliked by almost everyone.
• Program developers don’t want to prepare documentation.
• User documentation is often left to technical writers who do not necessarily know all
the details. Their documents are often initially incorrect, inconsistent and incomplete.
• The intended readers find the documentation to be poorly organized, poorly prepared
and unreliable; they do not want to use it. Most prefer “try it and see” or “look at the
code ” to relying on documentation.
• User documentation is often displaced by “help” systems because it is hard to find the
details that are sought in conventional documentation. Unfortunately, the “help”
system only answers a set of frequently occurring questions; it is usually incomplete
and redundant. Those with an unusual question don’t get much help.
• Computer Science researchers do not see software documentation as a research topic
They can see no mathematics, no algorithms, etc..
These factors feed each other in a vicious cycle.
Bad documentation is not used and does not get improved.
Middle Road Software, Inc.
David Lorge Parnas 3/56 Zurich documentation slides.pages
Why Real Improvement Is Difficult
“Nobody” does it that way.
• “Nobody” builds really good software (error free, easily maintained)
We don’t have time to write documents that nobody reads.
• “Never have time at the start, always have time at the end” (B.O. Evans)
“I have no idea how to do that” (Ph.D. developer, author)
• Nobody taught you how!
Finally, Dilbert’s view on making real changes:
• Ideas that would change the way we work can be very threatening.
Middle Road Software, Inc.
David Lorge Parnas 4/56 Zurich documentation slides.pages

Dilbert Knows That Documentation Is Important.
When people leave, knowledge leaves with them.
Middle Road Software, Inc.
David Lorge Parnas 5/56 Zurich documentation slides.pages
Programming Vs. Software Design
“Software design” is not just another name for programming.
Programming is only a small part of software development.
• “Software” refers to “a program or set of programs written by one group of
people for repeated use by another group of people”1. This is
fundamentally different from producing a program for a single use, or for your own
use.
• When producing a program for your own use, you can expect the user to understand
the program and to know how to use it. There is no need to prepare manuals that
explains what parameters mean, the format of the input, or compatibility issues. All
are required when preparing a program that will be used by strangers.
• When producing a program for a single use, there is no need to design a program that
will be easily maintained in several versions and no need to describe the design to
those who will have to change it.
It is the differences between software development and programming (multi-person
involvement, multi-version use) that make documentation important for software development.
Middle Road Software, Inc.
David Lorge Parnas 6/56 Zurich documentation slides.pages
1 Brian Randell was the first to point this out.
What Is Meant By “Document”
A record of design decisions that is binding, i.e. one restricts future
decisions. Deviations require an approved change.
To be as useful as possible documents must be:
• Accurate
• Consistent
• Complete (all decisions fully documented).
• Explicitly structured for easy retrieval and easy change.
Informal introductions/explanations are not documents in this sense.
Vague documents are like vague contracts2 they may be worse than
having no documents at all.
Middle Road Software, Inc.
David Lorge Parnas 7/56 Zurich documentation slides.pages
2 A design document is an essential part of a contract but not the whole contract.
A Preliminary Example: Dell Keyboard Checker
In daily use in Limerick for many years.
Believed to be completely correct.
Two informal descriptions totaling 21 pages (English).
• several ambiguities
• a few missing cases
• a few errors
Problem proposed as a challenge by a skeptical manager.
All information could be expressed in two pages
• preparation revealed errors in program and older descriptions
• new document much more precise and easily used.
• new document suitable as input to testing tools and inspection process.
Middle Road Software, Inc.
David Lorge Parnas 8/56 Zurich documentation slides.pages

Requirements For Keyboard Checker
Middle Road Software, Inc.
David Lorge Parnas 9/56 Zurich documentation slides.pages
No Theoretical Advantage
The document is a mathematical expression, equivalent to the one below.
The advantages are practical, not theoretical.
• fewer errors
• checkability
• ease of reference.
Keyboard Checker: Conventional Expression
(N(T)=2∧keyOK∧(¬(T=_)∧N(p(T))=1))∨(N(T)=1∧(T=_∨(¬(T=_)∧N(p(T))=1))∧
(¬keyOK∧¬prevkeyOK∧¬prevkeyesc))∨((¬(T=_)∧N(p(T))=1)∧
((¬keyOK∧keyesc∧¬prevkeyesc)∨(¬keyOK∧keyesc∧prevkeyesc∧
prevexpkeyesc))∨((N(T)=N(p(T))+1)∧(¬(T=_)∧(1<N(p(T))<L))∧(keyOK))∨
((N(T)=N(p(T))-1))∧(¬keyOK∧¬keyesc∧(¬prevkeyOK∧prevkeyesc∧
preprevkeyOK)∨prevkeyOK)∧((¬(T=_)∧(1<N(p(T))<L))∨(¬(T=_)∧N(p(T))=L)))∨
((N(T)=N(p(T)))∧(¬(T=_)∧(1<N(p(T))!L))∧((¬keyOK∧¬keyesc∧(¬prevkeyOK∧
prevkeyesc∧¬preprevkeyOK))∨(¬keyOK ∧¬prevkeyOK∧ ¬prevkeyesc)∨
(¬keyOK∧keyesc∧¬prevkeyesc)∨(¬keyOK∧keyesc∧prevkeyesc∧
prevexpkeyesc))∨((N(P(T)=Fail)∧(¬keyOK∧keyesc∧prevkeyesc∧
¬prevexpkeyesc)∧(1!N(p(T))!L))∨((N(P(T)=Pass)∧(¬(T= _)∧N(p(T))=L)∧(keyOK))
Software Quality Research Laboratory - University of Limerick - Ireland
42/56
David Parnas!! ! ! ! ! ! !! 2010 October 26 21:50 ENASE/ICSOFT slides
Middle Road Software, Inc.
David Lorge Parnas 10/56 Zurich documentation slides.pages
Completeness And Consistency
System Documentation is expected to be complete and consistent,
but...
• Individual documents are not expected to be complete descriptions;
they are complete relative to a document content specification.
• Unresolved Issues or missing information must be noted.
In connection with software, “document” is frequently used very
sloppily.
Information accompanying software often comes with disclaimers, i.e.,
statements that deny any claim to accuracy.
Middle Road Software, Inc.
David Lorge Parnas 11/56 Zurich documentation slides.pages
Are Computer Programs Self-documenting?
Code itself looks like a document.
In 2006, Brad Smith, Microsoft Senior Vice President and General Counsel,
said. “The Windows source code is the ultimate documentation of Windows
Server technologies”.
No such confusion with physical products; there is a clear difference
• between a circuit diagram and the circuit
• between a bridge and its documentation.
Nobody wants to crawl around to find the locations or capacity of pipes.
Code is commonly described as self documenting
• This may be true “in theory” but, in practice, it is a naive illusion or disingenuous.
• We need documents that contain the essential information, abstracting from the huge
amounts of information in the code that we do not need.
• We should be able to use the program without reading the code.
Middle Road Software, Inc.
David Lorge Parnas 12/56 Zurich documentation slides.pages

Internal Documentation Vs. Separate Documents
Nobody wants documentation distributed within a physical product.
Nobody wants to climb a bridge to determine the sizes of nuts and bolts
Drivers do not want to look at the bridge structure to know load limits.
We expect documentation to be separate from the product.
Some propose that assertions, or program functions, and similar
information be placed inside of the code.
• This is useful to the developers but not meet the needs of other
readers.
• Testers should be able to prepare “black box” test suites in advance of
completion.
• Programmers using a program should not have to read it.
Middle Road Software, Inc.
David Lorge Parnas 13/56 Zurich documentation slides.pages
Models Vs. Documents
Renewed interest in models and “model-driven engineering.”
Big difference between “model” and “document”.
Definition: A model of a product is a simplified depiction of that
product; a model may be physical (often reduced in size and detail)
or abstract.
• A model will have some important properties of the original.
• Not all properties of the model are properties of the actual system.
Definition: A mathematical model of a system is a mathematical
description of the properties of a model.
• Models can be very useful to developers but, because they are not necessarily
accurate descriptions, they may not always serve as documents.
• One can derive information from some models that is not true of the real system.
• Models must be used with great care;
• Every precise and accurate document can serve as a safe mathematical model
Middle Road Software, Inc.
David Lorge Parnas 14/56 Zurich documentation slides.pages
Design Documents Vs. Introductory Documentation
When a document is prepared, it may be intended for use either as a tutorial
narrative or as a reference work.
• Tutorial narratives are usually designed to be read from start to end.
• Reference works are designed so a reader can retrieve specific facts.
• Tutorials are intended for people with little previous knowledge about the subject.
• Reference documents are generally designed for people who already know a lot about
the subject but need to fill specific gaps in their knowledge.
Compare introductory language textbooks with dictionaries.
• Textbooks begin with the easier and more fundamental aspects of the language.
• Dictionaries arrange words in a specified order
• Narratives make poor reference works
• Reference works are a poor way to get an introduction to a subject.
We need both kinds of documents but this talk is about reference documents.
Middle Road Software, Inc.
David Lorge Parnas 15/56 Zurich documentation slides.pages
Specifications Vs. Other Descriptions (1)
Must be conscious of the role that a document will play in a development
process. There are two basic roles, description and specification.
• Descriptions provide properties of a product that exists (or once existed).
• Specifications are descriptions that state only required properties of a product.
• A specification that states all required properties is called a full specification.
• Descriptions may include properties that are incidental and not required.
• If a product does not satisfy a specification, it is not acceptable for the use intended.
The difference is one of intent, not form.
• Every specification that a product satisfies is a description of it.
• Notation is the same.
• This has confused many researchers.
• There is no such thing as a “specification language”.
Middle Road Software, Inc.
David Lorge Parnas 16/56 Zurich documentation slides.pages

Specifications Vs. Other Descriptions (2)
Distinction is important when one product is used as a component of another.
• The builder of the using product may assume that any replacements will still have the
properties stated in a specification.
• This is not true if the document is a description that is not a specification.
• Users should not rely on such documents.
Specifications impose obligations on the implementers, users, etc.
• When presented with a specification, implementers may either
• accept the task of implementing that specification, or
• reject the job completely, or
• report problems with the specification and propose a revision.
• Users must be able to count on the properties stated in a specification;
• Users must not base their work on any properties not stated in the specification.
• Purchasers are obligated to accept a product that meets the (full) specification
included in a purchase agreement or bid.
Middle Road Software, Inc.
David Lorge Parnas 17/56 Zurich documentation slides.pages
Extracted Documents
It is possible to produce description documents by examining the product.
• Extracted documents will be descriptions but not usually specifications.
• Observation or inspection cannot tell you what was intended or what is required.
• Extracted documents usually contain low-level information, not abstractions.
• Extracted documentation is of little value during development.
• Extracted documents not a valid guide for testers. Would be circular; You are assuming
that the code is correct and testing to see that it does what it does.
• Documentation based on comments can be untrustworthy
Javadoc like tools are of very limited use.
• Used by developers who do not want to document.
• Depend on comments.
Middle Road Software, Inc.
David Lorge Parnas 18/56 Zurich documentation slides.pages
Documents Are Not Programs
They must describe mappings from input to output without describing
the steps in a computation process or any other information that should
not be in the document3.
They must provide the exactly the information that the intended
readership needs in a way that is easy for them to use.
Our documents are mathematical expressions describing a function
that maps an input to an output.
• There should be no axioms,
• There should be no algebraic equations, and
• There should be expressions defining functions.
The expressions are evaluated as one evaluates x+2, i.e. substitute values and apply functions.
Middle Road Software, Inc.
David Lorge Parnas 19/56 Zurich documentation slides.pages
3 Content definitions for documents will be discussed later.
Roles Played By Documents In Development - 1
Documentation as the design medium
• Decisions are made by putting them in documents.
Documentation-based design reviews
• Creating documentation reveals problems
• Reviewing documentation is an early design review.
Documentation based code inspections
• Reviewing programs against their specification
• Reviewing the programs that use that program.
• Divide and conquer using hierarchical decoposition and displays
Documentation based revisions
• Maintainers need guidance
• Developers may have forgotten, quit, died, become managers…...
Middle Road Software, Inc.
David Lorge Parnas 20/56 Zurich documentation slides.pages

Roles Played By Documents In Development - 2
Documentation in contracts
• Specification of the set of acceptable deliverables is an essential part of contracts
• Contract also includes schedules, cost formulae, penalty clauses, statements about
jurisdictions for dispute settlement, warranty terms, etc.
Documentation is used to attribute blame and settle disputes
• Who did not conform?
• Which component is wrong?
Documentation and compatibility
• The chimera of interchangeable and reusable components will not be achieved
without a clear precise specification for those components.
Documentation as a way for the parties to communicate.
• Volker Gruhn’s observations: Communication the key determiner of success.
• Communication both when writing and afterwards.
Documentation key to distributed development.
Middle Road Software, Inc.
David Lorge Parnas 21/56 Zurich documentation slides.pages
Costs And Benefits Of Software Documentation
Documentation production costs are relatively easy to measure.
Much harder to measure the cost of not producing the documentation.
Losing time by adding people.
• Frederick P. Brooks, Jr.: Adding new staff to a late project can make it later.
• Newcomers need information Experienced staff become less productive
• Good documentation ameliorates the problem.
Wasting time searching for answers
• Documentation that is structured for information retrieval saves frustrating hours.
Wasting time because of incorrect and inconsistent information
The cost of detecting errors late or never
Time wasted in inefficient and ineffective design reviews
Malicious exploitation of undocumented properties by hackers
Middle Road Software, Inc.
David Lorge Parnas 22/56 Zurich documentation slides.pages
The Most Important Software Design Documents
Each project will have its own documentation requirements.
There is a small set of documents that is always needed. They are:
• The Systems Requirements document
• The Module Structure document (module guide, informal)
• Module interface documents
• Module internal design documents
• Program function documents
These will be discussed individually.
Middle Road Software, Inc.
David Lorge Parnas 23/56 Zurich documentation slides.pages
Considering Readers And Writers
Many separate documents because of variety of readers and writers
The readers have different needs; Writers have different information
No two documents have the same readers or creators.
The Main Documents
Document
Writers
Readers/Users
Software Requirements
Document
User reps, UI experts,
application experts,
controlled hardware
experts
Authors of module guide and
module interface specifications,
(Software “Architects”)
Module Guide
Software “Architects”
All Developers
Module Interface
Specifications
Software “Architects”
Developers who implement or
use the module
Program Uses Structure
Software “Architects”
Component Designers, Programmers
Module Implementation
Design Document
Component Designers
Programmers implementing
component
Display Method Program
Documentation
Programmers
implementing
component
inspectors, maintainers
potential reusers
This is a classic list but when it was new, we did not know how to do it.
Modules are collections of programs and data structures that are to be
produced by the same programmer or group of programmers.
Components are collections of programs that are shipped and used as a unit.
Middle Road Software
31/61
David Parnas! 20 May 2010 00:16 !!!!! !!! !!! !!! !! Iowa State DL slides.pages
Middle Road Software, Inc.
David Lorge Parnas 24/56 Zurich documentation slides.pages

What Makes Design Documentation Good?
Accuracy
• Statements must be true!
• Statements must be precise!
Lack of ambiguity
• NO possible differences in interpretations.
Completeness
• What should be there can be found
Ease of access
• Like a dictionary, not a textbook.
Middle Road Software, Inc.
David Lorge Parnas 25/56 Zurich documentation slides.pages
Documents And Mathematics
It is rare to speak of software documentation and mathematics together.
Documents are predicates
• We can write “document expressions” to characterize classes of products.
Mathematical definitions of document contents are needed.
• Avoid the endless discussions about what goes where
• Avoid duplication or missing information
Using mathematics in documents
• Necessary for accuracy, lack of ambiguity, completeness, and ease of access
• The contents of a document is defined abstractly as a set of relations
• Representation is a critical issue.
Middle Road Software, Inc.
David Lorge Parnas 26/56 Zurich documentation slides.pages
Requirements Documentation
A Professional Engineer must make sure that their products are fit for use.
This implies that an Engineer must know what the requirements are.
An Engineer need not determine them, but must check them.
Requirements are not limited to the conscious wishes of the customer.
Other requirements implied by the obligation of Engineers to protect the
safety, well-being and property of the general public.
Engineers should insist on having a complete, consistent, and unambiguous
document that is approved by the relevant parties..
No user visible decisions should be left to the programmers
The document should constrain the program designers.
Middle Road Software, Inc.
David Lorge Parnas 27/56 Zurich documentation slides.pages
The Two-variable Model For Requirements Documentation
The two-variable model has been used in many areas of engineering.
A product can be viewed as a black box with p inputs and q outputs.
• We are given no information about the internals.
• Values of controlled variables, c1,…, cq, are determined by the system.
• Values of monitored variables, m1,…, mp, are determined externally.
• Output values can depend immediately on the input values (i.e., without delay)
Monitored Controlled
Variables Variables
m2
mp-1
c1
mp
c2
cq-1
cq
●
●
●
●
●
●
m1
Middle Road Software, Inc.
David Lorge Parnas 28/56 Zurich documentation slides.pages

Notation
• MC denotes (m1, . . . mp, c1, . . . cq)
• M(MC) and C(MC) denote m1, . . . mp and c1, …, cq respectively.
• If S is a set of MC-tuples M(S) is a set defined by {q | (∃T, T ∍ S ∧ M(T) = q)} and C(S) is a set
defined by {q | ∃T, T ∍ S ∧ C(T) = q}.
• The values of a variable, v, over time can be described by a function of time denoted vt. The
expression vt(T) denotes the value of the vt at time T.
• The values of any tuple of variables, V, over time can be described by a function of time denoted
Vt. Vt(T) denotes the value of the Vt at time T.
• Viewing Vt as a set of ordered pairs of the form ( t, Vt(t)); the subset of Vt with t ! T will be
denoted VtT.
• The product’s possible behavior can be described by a predicate, SYSP(MCtT) where:
• MCtT is a history of the monitored and controlled values up to time T,
• SYSP(MCtT) is true if and only if MCtT describes possible behaviour of the system.
• SYS = {(m, c) | (∃ mc, SYSP(mc) ∧ C(mc) =c ∧ M(mc) =m)}
Notes:
• Conventional mathematics, understandable 100 years ago.
Middle Road Software, Inc.
David Lorge Parnas 29/56 Zurich documentation slides.pages
Non-Determinism
In deterministic systems, the output values are a function of the input.
• The values of outputs in the history are redundant.
• We can treat SYS as a function: domain: values of MtT, range: values of CtT.
• SYS(MtT)(T) evaluates to the value of the outputs at time T.
In deterministic case, there are two complicating factors:
• Relation SYS would not necessarily be a function.
• The output may be constrained by previous output values, not just the input values.4
In the general case output values must be included in history descriptions.
For a 2-variable system requirements document we need two predicates NATP
and REQP. These are discussed next.
Middle Road Software, Inc.
David Lorge Parnas 30/56 Zurich documentation slides.pages
4 A simple example to illustrate this problem is the classic probability problem of drawing uniquely numbered balls from an
opaque urn without replacing a ball after it is removed from the urn. The value that has been drawn cannot be drawn
again, but except for that constraint, the output value is random.
Relation NAT
Nature constrains the values of environmental quantities.
Constraints described by a predicate, NATP(MCtT),"where:
• MCtT is a history of the input and output variable values up to, and including,
time, T and,
• NATP(MCtT) if and only if MCtT describes possible behaviour of the product’s environment.
Convenient to represent NATP as a relation, NAT,
• domain comprising values of MCtT
• range comprising values of CtT.
This is defined by:
• NAT = {(m, c) | (∃ mc, NATP(mc) ∧ C(mc) =c ∧ M(mc) =m)}
Middle Road Software, Inc.
David Lorge Parnas 31/56 Zurich documentation slides.pages
Relation REQ
No product can override NAT (if you try, contradictions arise)
• Can only impose stricter constraints on the values of the output variables.
• The restrictions can be documented by a predicate, REQP(MCtT), where:
• MCtT is a history of the monitored and controlled variable values up
to, and including, time T and,
• REQP(MCtT) is true if and only if MCtT describes permissible behavior of the
system.
It is sometimes convenient to represent REQP as a relation, REQ,
• Domain comprising values of MCtT
• Range comprising values of Ct(T).
This is defined by:
• REQ = {(m, c) | (∃ mc, REQP(mc) ∧ C(mc) =c ∧ M(mc) =m)}
If deterministic behaviour is required, we can write REQ (MtT), a function with values in the
range, Ct(T).
Middle Road Software, Inc.
David Lorge Parnas 32/56 Zurich documentation slides.pages

Experience And Examples: Requirements
Numerous requirements documents written using this model.
• A-7 OFP [HKPS] [Heninger].
• Pilots found hundreds of detail errors
• Programmers coded from document
• Bell Laboratories SES
• Copied by others
• “Shortest soak time”
• Darlington Nuclear Power Generating Plant
• basis for a successful inspection
• Dell keyboard checker
• Found errors in existing documents, 21 pages reduced to 2
Continued by NRL/SCR.
We could do better today.
Middle Road Software, Inc.
David Lorge Parnas 33/56 Zurich documentation slides.pages
Interfaces
One of the most important, and least well understood,
concepts in Software Engineering.
Often, confused with syntax of invocations or a shared data
structure.
Definition: Interface
Given two communicating software components, A and B, B’s
interface to A is the weakest assumption about B that would allow
you to prove that A is correct.
Any change in B that invalidates its interface to A means
that, A could not be proven correct and should be changed.
Interfaces determine the difficulty of changing software.
Middle Road Software, Inc.
David Lorge Parnas 34/56 Zurich documentation slides.pages
Surprising Observations About Interfaces.
• There isn’t necessarily a 1:1 relation between a program and an interface.
• Interfaces not symmetric. B’s interface to A differs from A’s interface to B.
• B may have an interface to A even if A does not have an interface to B.
• A component may have a specified interface. This tells the developers of other
programs what they may assume about the specified component.
• If the developers of a component, A, make use of facts about a specified component,
B, that are not implied by B’s specified interface, the actual interface is stronger than
the specified interface and A should be considered incorrect (even if it is working).
• B may have an interface with A even if neither invokes the other. For example, the
correctness of A may depend on B maintaining a shared data structure with certain
properties.
• Published interface (assumption that can be made by all) should imply the actual pair-
wise interfaces but sometimes does not (bad error).
Middle Road Software, Inc.
David Lorge Parnas 35/56 Zurich documentation slides.pages
Software Component Interface Documents
Two-variable model can be applied to software components
Discrete event version of the two-variable model, known as the Trace Function
Method (TFM) can be used.
TFM has been found useful for several industrial products as described in .
TFM documents are
• easily used as reference documents,
• can be checked for completeness and consistency
• can be input to simulators for evaluation of the design and testing an implementation.
• can be reviewed by practitioners who reported many detailed factual errors
If people cannot read a document, they will not find faults in it.
Middle Road Software, Inc.
David Lorge Parnas 36/56 Zurich documentation slides.pages

TFM For Keyboard Checking Tool
One of 2 pages - replaced 21 faulty pages of text.
Keyboard Checker: Tabular ExpressionKeyboard Checker: Tabular ExpressionKeyboard Checker: Tabular ExpressionKeyboard Checker: Tabular ExpressionKeyboard Checker: Tabular ExpressionKeyboard Checker: Tabular ExpressionKeyboard Checker: Tabular ExpressionKeyboard Checker: Tabular ExpressionKeyboard Checker: Tabular ExpressionKeyboard Checker: Tabular Expression
N(T) =
N(T) =
N(T) =
N(T) =
T=_
¬ (T= _) !
¬ (T= _) !
¬ (T= _) !
T=_
¬ (T= _) !
¬ (T= _) !
¬ (T= _) !
T=_
N(p(T))=1
1<N(p(T))< L
N(p(T))= L
keyOK
keyOK
keyOK
keyOK
keyOK
2
N(p(T))+ 1
Pass
¬keyOK ∧
¬keyesc
∧
(¬prevkeyOK ! prevkeyesc !
preprevkeyOK) " prevkeyOK
(¬prevkeyOK ! prevkeyesc !
preprevkeyOK) " prevkeyOK
(¬prevkeyOK ! prevkeyesc !
preprevkeyOK) " prevkeyOK
N(p(T)) - 1
N(p(T)) - 1
¬keyOK ∧
¬keyesc
∧
¬prevkeyOK ! prevkeyesc !
¬preprevkeyOK
¬prevkeyOK ! prevkeyesc !
¬preprevkeyOK
¬prevkeyOK ! prevkeyesc !
¬preprevkeyOK
N(p(T))
N(p(T))
¬keyOK ∧
¬keyesc
∧
¬prevkeyOK ! ¬ prevkeyesc
¬prevkeyOK ! ¬ prevkeyesc
¬prevkeyOK ! ¬ prevkeyesc
1
1
N(p(T))
N(p(T))
¬keyOK ∧
keyesc
∧
¬ prevkeyesc
¬ prevkeyesc
¬ prevkeyesc
1
N(p(T))
N(p(T))
¬keyOK ∧
keyesc
∧
prevkeyesc ! ¬prevexpkeyesc
prevkeyesc ! ¬prevexpkeyesc
prevkeyesc ! ¬prevexpkeyesc
Fail
Fail
Fail
¬keyOK ∧
keyesc
∧
prevkeyesc ! prevexpkeyesc
prevkeyesc ! prevexpkeyesc
prevkeyesc ! prevexpkeyesc
1
N(p(T))
N(p(T))
Middle Road Software, Inc.
David Lorge Parnas 37/56 Zurich documentation slides.pages
Equivalent Conventional Expression
Theoretically equivalent but will not be read or checked.
Keyboard Checker: Conventional Expression
(N(T)=2∧keyOK∧(¬(T=_)∧N(p(T))=1))∨(N(T)=1∧(T=_∨(¬(T=_)∧N(p(T))=1))∧
(¬keyOK∧¬prevkeyOK∧¬prevkeyesc))∨((¬(T=_)∧N(p(T))=1)∧
((¬keyOK∧keyesc∧¬prevkeyesc)∨(¬keyOK∧keyesc∧prevkeyesc∧
prevexpkeyesc))∨((N(T)=N(p(T))+1)∧(¬(T=_)∧(1<N(p(T))<L))∧(keyOK))∨
((N(T)=N(p(T))-1))∧(¬keyOK∧¬keyesc∧(¬prevkeyOK∧prevkeyesc∧
preprevkeyOK)∨prevkeyOK)∧((¬(T=_)∧(1<N(p(T))<L))∨(¬(T=_)∧N(p(T))=L)))∨
((N(T)=N(p(T)))∧(¬(T=_)∧(1<N(p(T))!L))∧((¬keyOK∧¬keyesc∧(¬prevkeyOK∧
prevkeyesc∧¬preprevkeyOK))∨(¬keyOK ∧¬prevkeyOK∧ ¬prevkeyesc)∨
(¬keyOK∧keyesc∧¬prevkeyesc)∨(¬keyOK∧keyesc∧prevkeyesc∧
prevexpkeyesc))∨((N(P(T)=Fail)∧(¬keyOK∧keyesc∧prevkeyesc∧
¬prevexpkeyesc)∧(1!N(p(T))!L))∨((N(P(T)=Pass)∧(¬(T= _)∧N(p(T))=L)∧(keyOK))
Middle Road Software, Inc.
David Lorge Parnas 38/56 Zurich documentation slides.pages
Extract From Module Interface Document
Output Functions
hr(T) 󲰨
PGM(r(T)) = SET HR 󲰙
0 ! !in(r(T)) < 24
"in(r(T))
¬ (0 ! in(r(T)) < 24)
hr((p(T)))
PGM(r(T)) = SET MIN
hr((p(T)))
PGM(r(T)) = INC 󲰙
min(p(T))= 59 󲰙
hr(p(T))= 23
0
¬ hr(p(T))= 23
1+ hr((p(T)))
¬ (min(p(T))=59)
hr((p(T)))
PGM(r(T)) = DEC
󲰙
¬ (min(p(T))= 0)
hr((p(T)))
min(p(T))= 0 󲰙
¬ (hr(p(T)))= 0
hr((p(T)))-1
hr(p(T))= 0
23
T= _
0
34/42
David Parnas### # # # # # # 2008 May 23 16:33 # # # # TFM slides 2008 slides
Middle Road Software, Inc.
David Lorge Parnas 39/56 Zurich documentation slides.pages
Program Function Documents
Those who use a program need not know how it does its job.
They want to know what job it does or is supposed to do.
Terminating deterministic program can be described by a function mapping
from a starting state to a stopping state.
States represented in terms of the values of program variables.
Theoretically, non-deterministic programs can be described a relation from
starting state to stopping states with a special element for non-determination.
In practice, LD-relation (relation plus termination set) is better.
• No special state that is hard to represent is needed.
Mathematically equivalent but better in practice.
Tabular expressions make it work in practice.
Big programs, well-written, can have small tables.
Middle Road Software, Inc.
David Lorge Parnas 40/56 Zurich documentation slides.pages

Example Of Program-Function Table
DEPARTMENT OF COMPUTING AND SOFTWARE •SOFTWARE QUALITY RESEARCH LABORATORY •CONNECTING THEORY WITH PRACTICE
McMaster University 69
8 June 2002 16:00
InspectwithNever.fm
DISPL
A
Y
2
(
Continued
)
Program
(
Repeated
)
New variable (to be declared in the embedding block):var med : integer;
Program statements:
{Body}
while not found and (low ! high) do begin
med := (low + high) div 2;
Test
end
Specifications o
f
Subprograms
END OF DISPL
A
Y
2
Test external variables: e, V, index, found, low, high, med (on Display 3)
R3(,) = (‘low ! ‘med ! ‘high) "
‘V[‘med]
< ‘e = ‘e > ‘e
index’ | true index’ = ‘med true
found’
=
‘found true ‘found
low’
=
‘med + 1 ‘low ‘low
high’
=
‘high ‘high ‘med # 1 $ NC(e, V, med)
Middle Road Software, Inc.
David Lorge Parnas 41/56 Zurich documentation slides.pages
Program-Function For A Poor (real) Program
• SOFTWARE QUALITY RESEARCH LABORATORY •
University of Limerick 34 /53
Luxinspectslides.fm
19 October 2005 22:48 Tabular Description of Reactor Shutdown Code
‘|OKTT| = .FALSE. (‘|OKTT| = .TRUE.) AND
NOT !NoSensTrip!
(‘|OKTT| = .TRUE.) AND .
!NoSensTrip!)
B(‘|PTB|,||DOW1||’) B(‘|PTB|,‘||DOW1||
.OR.‘#TMASK(‘|PTB|)#)
Table 4 B(‘|PTB,‘||DOW1||
.OR.‘#TMASK(‘|PTB|)#)
B(‘#CN#,||DOW2||’) B(‘#CN#,‘||DOW2||) Table 4 B(‘#CN#,‘||DOW2||)
B(‘#CND#,||DOW2||’) B(‘#CND#,‘||DOW2||) Table 4 B(‘#CND#,‘||DOW2||)
||EX||’ ‘||EX|| .OR. ‘|MASK| ‘||EX|| .OR. ‘|MASK| ‘||EX|| .OR. ‘|MASK|
|HI1|’ ‘|HI1| ‘//HTL(5)// - ‘|HYS| ‘//HTL(5)// - ‘|HYS|
|HI2|’ ‘|HI2| ‘//HTL(5)// ‘//THL(5)//
|LO1|’ ‘|LO1| ‘//LTL(5)// ‘//LTL(5)//
|LO2|’ ‘|LO2| ‘//LTL(5)// = ‘|HYS| ‘//LTL(5)// + ‘|HYS|
||MC||’ ‘||MC|| Table 4 0
||PC||’ ’||PC|| Table 4 0
B(j,|STBV|’), j = ‘|STB| + j-1, i in {1...5} B(j,‘|STBV|) Table 3 Table 3
B(j,|STBV|’),
NOT (j in {‘|STB| + i-1}, i in {1...5})
B(j,(‘|STBV|)
AND. ‘|UM|))
B(j,(‘||STW||
.AND. ‘|UM|))
B(‘|STB| + i-1,||STW||’), i in {1...5} B(‘|STB| + i-1,
(‘||STW|| .OR. ‘|UM|))
Table 3 Table 3
B(j,||STW||’), NOT (j in {‘|STB| + i-1}, B(i,(‘||STW|| .OR. ‘|UM|)) B(i,‘||STW||) B(i,‘||STW||)
B(‘|TIB|,||TIW||’) B(‘|TIB|,(‘||TIW||
.OR.‘#TMASK(‘|TIB|)#))
B(‘|TIB|,(‘||TIW||
.AND.‘#FMASK(‘|TIB|)#))
B(‘|TIB|,(‘||TIW||
.AND.‘#FMASK(‘|TIB|)#))
||HIF(1...5)||’ ‘||HIF(1...5)|| Table 2 Table 2
|I|’ ‘|I| 6 6
||LOF(1...5)||’ ‘||LOF(1...5)|| Table 2 Table 2
Middle Road Software, Inc.
David Lorge Parnas 42/56 Zurich documentation slides.pages
Module Internal Design Documents
Design of a software component is documented by describing: (Many authors)
• the hidden internal data structure,
• the program functions of each externally accessible program, i.e their
effect on the hidden data structure,
• an abstraction relation mapping between internal states and the
externally distinguishable states of the objects created by the module.
The data structure can be described by programming language declarations.
The functions are usually best represented using tabular expressions.
Easily extended to non-deterministic case using relations.
Middle Road Software, Inc.
David Lorge Parnas 43/56 Zurich documentation slides.pages
Checking An Internal Design
Design documentation should allow us to verify the workability of a design.
The information is there for an informal check.
No examples yet.
How can the workability of a design be verified?
For all possible events, e, the following must hold:
AR(d1,t1) ∧ e(d1,d2) = AR(d2,t1.e)
Middle Road Software, Inc.
David Lorge Parnas 44/56 Zurich documentation slides.pages

Additional Documents
• In addition to the system requirements document, which treats
hardware and software as an integrated single unit, it is sometimes
useful to write a software requirements document
• An informal document known as the module guide
• A uses relation document, which indicates which programs are used
by each program is generally useful. The information is a binary
relation and may be represented in either tabular or graphical form.
• In systems with concurrency, process structure documents are useful.
• The “gives work to” document is useful for deadlock prevention.
• Interprocess/component communication should also be documented
Middle Road Software, Inc.
David Lorge Parnas 45/56 Zurich documentation slides.pages
Tabular Expressions For Documentation
Mathematical expressions that describe computer systems can become very
complex, hard to write and hard to read.
As first demonstrated in 1977, the use of a tabular format for mathematical
expressions can turn an unreadable symbol string into an easy to access
complete and unambiguous document.
Middle Road Software, Inc.
David Lorge Parnas 46/56 Zurich documentation slides.pages
There Are Many Forms Of Tabular Expressions.
• The grids need not be rectangular.
• A variety of types of tabular expressions are illustrated and defined
[Jin].
• [Jin], defines the meaning of these expressions by means of
translation schema to an equivalent conventional expression.
• Good basis for tools.
• The appropriate table form will depend on the characteristics of the
function being described.
Middle Road Software, Inc.
David Lorge Parnas 47/56 Zurich documentation slides.pages
Tables Like This Can Be Found On The Internet
Ticket Price
1 Passenger
2 Passengers
3 - 5 Passengers
6 o r m o r e
Passengers
0 - 100
101 - 200
201 - 300
301 and more
35
45
55
65
40
50
60
70
45
55
65
75
50
60
70
70 + 1 0 p er
passenger
Middle Road Software, Inc.
David Lorge Parnas 48/56 Zurich documentation slides.pages

This Says The Same Thing
P=1
P=2
2 < P < 6
P > 5
0 < T ! 100
100 < T ! 200
200 < T ! 300
T > 300
35
45
55
65
40
50
60
70
45
55
65
75
50
60
70
70 + 10 "(P-5)
The above is a tabular mathematical expression.
Middle Road Software, Inc.
David Lorge Parnas 49/56 Zurich documentation slides.pages
This Too Is A Mathematical Expression
BMI
T[1]
p<
88
88!
p<
110
110
!p<
121
121
!p<
132
132
!p<
154
154
!p<
176
176
!p<
198
198
!p<
220
220
!p<
110
242
!p<
265
p>
265
T[4]
T[0]
T[2]
1.9!m<2
very talll
1.8!m<1.9
talll
1.7!m<1.8
avg
1.6!m<1.7
middle
1.5!m<1.6
short
m!1.5
very short
k<
40
40
!
k<
50
50
!k
<
55
55
!k
<
60
60
!k
<
70
70
!k
<
80
80
!k
<
90
90!
k<
100
100
!k<
110
110
!k<
120
k>
120
T[3]
underweight
low
borderline
normal
low
overweight
overweight
very
overweight
OBESE!
Middle Road Software, Inc.
David Lorge Parnas 50/56 Zurich documentation slides.pages
A Circular Table
Middle Road Software, Inc.
David Lorge Parnas 51/56 Zurich documentation slides.pages
The Bottom Lines:
Producing no documentation gets you in trouble.
Producing bad documentation might be worse.
Producing good documentation:
• will help you get the requirements right
• will help you get interfaces right
• will help you in your testing
• will help you in your inspections
• will help you in maintenance and upgrades
• will help you manage a product line effectively.
Define the content of each document (as illustrated)
Use appropriate (mathematical) tabular expressions
Middle Road Software, Inc.
David Lorge Parnas 52/56 Zurich documentation slides.pages

Management’s Role In Document Driven Design
Management is getting something done without knowing exactly what
it is (and much more).
Management can undermine any effort by either not demanding it, not
leaving time for it, or not supporting it.
• Insist that if it isn’t done, it is not documented.
• Schedule document reviews
• Insist that software testers test against documents using the
documents to generate oracles and test cases.
• Insist on document guided inspections for critical parts.
• Allow no change without revising the associated documents.
Without management support it won’t work!
Middle Road Software, Inc.
David Lorge Parnas 53/56 Zurich documentation slides.pages
Research Problems
More documents (e.g. sequential process structure)
Various forms of composition given these documents
Reliability given these documents
More table types
More examples (publishable)
Tools that are more than Masters theses
• input tools
• format tools
• better checking tools
• better simplification tools
• composition (relational) tools
Middle Road Software, Inc.
David Lorge Parnas 54/56 Zurich documentation slides.pages
Summary And Outlook
It is important to the future of software engineering to learn how to replace
today’s documentation with precise professional design documents.
Documents have a mathematical meaning and are mathematical expressions.
Those expressions can be in a tabular formats.
These have proven to be practical over a period of more than 30 years.
There is much room for improvement and research is needed.
No more “cut and try” software development.
Software has become a serious industry that produces critical products.
The first step towards maturity must be to take documentation seriously
When our documentation improves in quality, the software quality will
improve too.
Middle Road Software, Inc.
David Lorge Parnas 55/56 Zurich documentation slides.pages
Thank You
Questions?
Discussion?
Shoes?
•
Middle Road Software, Inc.
David Lorge Parnas 56/56 Zurich documentation slides.pages