Design issues

In this section describe the key design decisions. This includes interface and abstract semantics design decisions, and why particular algorithms and data structures were chosen, versus alternatives. Remember that this documentation is not for the end-user, and thus may be more technical than the User's Guide.

As much as possible, separate the design issues into an abstraction level and an implementation level:

• The abstraction level design issues concern the interface, semantics, and performance requirements.
• The implementation level design issues concern the choice of internal algorithms and data structures that meet the abstraction level requirements. Do not discuss details that would be obvious from reading the code, but if you have used nonobvious optimizations in your code then either here or the next section (source code) is the place to describe them.

Occasionally you may need to refer to some of the implementation issues in justifying your abstraction level design choices.

Some further points:

• It may be useful to make comparisons to other libraries or software packages. Though not essential, such comparisons can help readers who might have knowledge of other software put your library in perspective. Avoid comparisons to software that is not widely known, since only a few people would be able to appreciate the comparison. Also avoid denigrating competing software or design decisions with phrases like "an awful hack"; keep your comparisons on a technical basis.
• Give a detailed rationale for your design decisions if you think it will either (1) help convince readers to use your software, or (2) help future maintainers, re-implementors, or extenders of your software to avoid making other design choices that you know are inferior (because you tried them, or rejected them on the basis of careful analysis).
• By the same token, avoid rationalizing decisions for which you have little supporting evidence; it's better simply to say that other decisions were possible but were not explored.