Software Engineering Documentation

• Using EiffelStudio IDE for producing documentation, e.g. in html or RTF form. For an example of chart view, contract view and text view in an RTF format, see here. RTF format is useful in documentation of software using Word.
• BON or UML class diagrams.
  • Using EiffelStudio IDE to produce BON class diagrams from the program text (automatically)
  • BON template. A template for producing high quality BON class diagrams (in detail with contracts) for import into Word.
• A Word template for documenting the design of your software is provided at the bottom of this page. The above facilities are useful for producing professional high quality documentation with clear images and accurate representations of the program text in differing views.

Software design is a process by which the software requirements are translated into a representation of software components, interfaces, and data necessary for the implementation phase. The SDD describes how the software system will be structured to satisfy the requirements.

The SDD is the primary reference for code development and, therefore, it must contain all the information required by a programmer to write the code. On the other hand, the SDD must be free of implementation detail.

An SDD is not a “stream of consciousness” (disorganized collection of the designer’s thoughts) nor is it a “stream of execution” (describing the order in which things will happen when it runs). The SDD should not suffer from:

• Poor Organization (mostly “stream of consciousness” or “stream of execution”). With this style, it is nearly impossible to find anything when you look for it.
• Boring prose (too many word/paragraphs when a crisp description, formula or diagram suffices).
• Confusing/inconsistent terminology
• Myopic viewpoint (too close to system when written)

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.

But what happens without documentation? When people leave, knowledge leaves with them (Dilbert):

How much paper is enough?

The title of this section comes from Better Embedded System Software, by Philip Koopman, Carnegie Mellon University (2010). He writes that every piece of paper should be forced to earn its keep as a useful document. We do not want to generate useless paper.

Writing a design document after the work is done is less likely to produce a useful document. The point of a design document is to help with the design process itself. So what should be in the design document?

• The design document describes the software architecture as a set of modules (components), their behaviour and their interconnections within the system.
• Every design document should have, as a minimum, a boxes and arrows diagram (with well-defined meanings) that describes the overall structure. In OO designs, we use BON and UML. The diagram fits on a single page, is clean and relevant (no small fonts).
• On subsequent pages, provide more detail of each module. Each component must have a clean interface and its operations are specified via contracts (preconditions, post-conditions and class invariants).
• Each design diagram or module description must fit on a single page.
• A Design must be free of implementation detail. It is not a line by line description of the code. Comments are not a design.
• The documentation must be at the appropriate level of abstraction (one that makes the design simpler to understand).
• The design document must be complete – it must contain all the information needed by the programmers who must implement the system.

Risks of not having a good design documentation

Occasionally, software can be created by jumping straight to coding. However, the larger the project, the bigger the risks.

• There is a delay in finding mistakes in the (undocumented) design only at implementation time when the cost of fixing the mistake can be orders of magnitude larger.
• The implementation is messy and unmaintainable. If you experience early code wear-out (brittle/disorganized code) then look to improving the design document.
• High defect rates result in increased development costs.
• A description of the architecture that is messy means you have a messy architecture!
• If programmers have difficulty understanding where their component fits into the big picture the project is likely to fail. Look to simplifying the design document.
• If your project fails to be completed then look to improving your design document.

• Template for EECS3311 project – click this link, login and download either pdf or doc.
• BON and UML. We use BON for class diagrams, and UML for statecharts and sequence diagrams.

The IEEE also has a template for a Software Design Document (SDD). It is provided here for your information, and is based on IEEE 1016-1998. However, you are encouraged to use the template above for 3311 Design Documentation.