Up Next
Go up to Documentation Requirements and Guidelines
Go forward to User documentation of generic software components

User documentation vs. design documentation vs. code documentation

  • 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.


 

Up Next