- User documentation: What a user needs to know to use
the software components to build applications; concerned with
interface and abstract semantics, not with implementation. User
documentation is best separated into a User's Guide, which introduces
the software gently through key ideas, examples, and other tutorial material,
and a Reference Manual, which more precisely and completely fills in
the details.
- Design documentation: Why the software is designed
as it is, mainly for benefit of present and future maintainers of the
software; giving the rationale for interface and abstract design
decisions, for the choice of particular algorithms and data
structures, versus alternatives; this documentation is not for the
user.
- Code documentation: How the components are
implemented--coding details and design decisions that are not obvious
from the code; this is not for the user but mainly for later
maintainers of the code.
User documentation should not refer to the implementation design,
except perhaps to help explain how components fit together (the
framework); if it refers to the algorithms, data structures, or
actual code, it should be only for the benefit of users who may like
to know, but the information given should not be essential to proper
use of a component.
For example, consider the SGI STL
sort function
description, which describes
- what it does
- performance bounds
- stability properties
Whether it uses quicksort, merge sort, radix sort, heapsort, etc., is
not (necessarily) of interest to the user. But note that for this to be
true, all three of the above parts of the description must be present.
It might be mentioned in the documentation that (a version of)
quicksort or introsort is the algorithm used to implement the
component, but it should not be necessary for the user to know this.
User documentation is also a contract that must be maintained when code
(and perhaps the whole implementation design) later changes.
|