Design documentation is the set of documents that accompany a design that explains both the details of the design and the decisions that went into the design. This documentation has two distinct roles. First, users of the design need to understand the interface and functionality of the design. Second, maintainers need to understand the details and the reason for those details in order to be able to change the design or come up with new designs. We generally call the first the Design Specification and the second the Detailed Design Document. The specification is sufficiently detailed that a skilled engineer can construct it, while the Detailed Design Document gives all the details of the finished design.
Systems are designed hierarchically as collections of components. Each component will have both a Design Specification and a Detailed Design. Typically the design spec is generated when the system architecture is designed, at least down to the level where the component design is not clear. As the system components are designed in detail, the Detailed Design is added to the Design Spec to form the complete design documentation. Of course, the Design Spec will evolve as the design proceeds.
The design spec of a component comprises an interface specification and a description of the functionality. Although these are two distinct parts of the specification, they depend on each other. The design spec must be done before the component is implemented – this is not documentation produced after the fact.
This design spec acts more as a requirements document before the component is designed. For example, it may only specify the minimum performance. Once the design has been completed, and the actual performance and timing are known, the spec is then finalized. It is often useful to keep the original requirements document to understand what part of the design was required and what a result of implementation decisions.
This describes the input and output signals of the component, including timing specifications and electrical characteristics.
This describes the functionality of the component in sufficient detail that a skilled engineer can design the component. For complex components such as the top level of a system, this may be very complex, such as the ISA of a processor. It is sometimes difficult to make sure there are no hidden assumptions in this spec.
Here is an example of a FIFO design specification.
This is the documentation that is produced when the component is implemented and describes all the design decisions and their rationale, along with the design itself. This documentation evolves as the implementation evolves, starting with the design specification and ending with the complete Detailed Design Document. This documentation is used during design for engineering design reviews, where the designer solicits comments and advice.
Complex components and systems will necessarily have many pages of documentation, including block diagrams of complex components, component specifications and interface descriptions. Primitive components may have relatively short documentation that is included, for example, in the Verilog file itself. For more complex Verilog components, a separate document with diagrams and more explanation may be needed.
All good designers use design reviews to make sure they have not overlooked a better solution or, even worse, have a design that will not work. Although design reviews take time, they save even more time by finding problems early and avoiding costly redesigns. Just the process of documenting and presenting a design will often give the lots of ideas for improvement. Design reviews also keep other team members up-to-date on the design.
Engineering design-review packages are detailed yet concise
descriptions of your design. Their purpose is (1) to force you to think through
all the details of a design, (2) to allow another engineer to understand your
design, and (3) to provide a permanent record of your design. They should
include the work you have accomplished, a description of what you must do to
complete the design, and they must identify potential problem areas. A good
package will help your reviewer find problems with your design, so you can
solve them early rather than later.
Use the following outline for your review packages:
In your final design package and in your final report, you must respond to each and every one of the recommendations your reviewers made on your preliminary design package and final design package, respectively. You should address the reviews point-by-point, by analyzing each recommendation on technical grounds, and then either:
The final report describes all the technical details of your design. It is a superset of your final design package, and should include all the information from your final design package *plus*
After you have a final design package, item (3) is the only one that should take you any real time. You should take data showing that your project is completely functional, with numbers if appropriate.