|
PC/CP300: Electronics Laboratory II
Documentation Standards
The following documentation standards are taken directly from
John F. Wakerly, Digital Design: Principles & Practices,
Third Edition Updated, Prentice Hall, 2001, pp312-313. This text
has been
used
for PC319 Digital Systems Design. John did such a good job describing
current industry documentation standards that we felt no value would be
added by rephrasing his original work.
"Good documentation is essential for correct design and
efficient maintenance of digital systems. In addition to being accurate
and complete, documentation must be somewhat instructive, so that a test
engineer, maintenance technician, or even the original design engineer
(six months after designing the circuit) can figure out how the system
works just by reading the documentation.
Although the type of documentation depends on system
complexity and the engineering and manufacturing environments, a
documentation package should generally contain at least the following
six items:
- A specification describes exactly what the
circuit
or system is supposed to do, including a description of all inputs and
outputs ("interfaces") and the functions that are to be
performed. Note that the "spec" doesn't have to specify how
the system achieves its results, just what the results are supposed to
be. However, in many companies it is common practice also to incorporate
one or more of the documents below into the spec to describe how the
system works at the same time.
- A block diagram is an informal pictorial
description of the system's major functional modules and their basic
interconnections.
- A schematic diagram is a formal
specification
of
the electrical components of the system, their interconnections, and all
the details needed to construct the system, including IC types,
reference designators, and pin numbers. We've been using the term logic
diagram for an informal drawing that does not have quite this level of
detail. Most schematic drawing programs have the ability to generate a
bill of materials (BOM) from the schematic; this tells the purchasing
department what electrical components they have to order to build the
system.
- A circuit description is a narrative text
document
that, in conjunction with the other documentation, explains how the
circuit works internally. The circuit description should list any
assumptions and potential pitfalls in the circuit's design and
operation, and point out the use of any nonobvious design
"tricks". A good circuit description also contains definitions
of acronyms and other specialized terms and has references to related
documents."
"The last area of documentation, the circuit
description, is very important in practice. Just as an experienced
programmer creates a program design document before beginning to write
code, an experienced logic designer starts writing the circuit
description before drawing the schematic. Unfortunately, the circuit
description is sometimes the last document to be created, and sometimes
it's never written at all. A circuit without a description is difficult
to debug, manufacture, test, maintain, modify, and enhance."
|
