Documentation for a product generally consists of three parts:
- Introductory material that provides a general description of the product and its features.
- Task-oriented, procedural information that describes how to use the features of the product to achieve the desired result.
- Reference information that describes the functions of lower-level components of the product.
These three types of information are typically included in the documentation for consumer products like dishwashers and user application software, as well as engineering products like MCUs and software drivers for embedded peripherals. But with engineering products, the technical reference documentation plays a far greater role in the successful use of the product.
A well-designed consumer product, no matter complex it may be under-the-hood, usually comes with a relatively short user manual with little, if any, technical reference information. The consumer often already knows how to use the product and may only read the product’s technical specifications when comparing products to make a purchasing decision. For example, after the first use of the product, a consumer using a dishwasher will usually just add detergent, choose a cycle, and hit the start button, without reading the instructions or looking up specifications like noise level or cycle time. Modern automobiles are technically complex machines, but have a commonly understood set of user controls. Technical specifications like compression ratio and torque are important from a performance/maintenance perspective, but we don’t need to know these things to operate the car.
Engineering products, on the other hand, do not follow such a consistent user interface paradigm. For example, ICs generally look alike but vary widely in function. MCUs from different vendors may be comparable in features and performance, but mostly include different CPU cores and vendor-specific peripherals with unique register sets. Drivers for embedded peripherals, if provided by the MCU vendor, have product-specific APIs. An engineer needs to know these details before using an IC for any purpose.
Another important distinction between a consumer product and an engineering product is that engineering products are generally used as building blocks in a higher-level system or product. An engineer uses an engineering product creatively to design something that doesn't already exist. We can assume that an MCU will be mounted onto a circuit board and programmed to do something. But to do either of those things successfully, an engineer needs detailed and accurate reference documentation. A hardware designer needs to know the function and electrical properties of the device's pins. A software engineer designing a peripheral driver needs to know the peripheral's programming model: the addresses and bitfield usage of the peripheral's registers. Designers of higher-level system software need to know the APIs presented by the peripheral drivers.
Qualities of reference documentation include accuracy, completeness, and ease of navigation. Of these, accuracy is the most important. Wrong information can lead to a design that doesn't work or, even worse, a design that appears to work correctly but has a hidden flaw. Such mistakes can be costly as best and dangerous at their worst.
Completeness is also important and can vary between product reference documentation from different vendors. Completeness is reflected not only in every necessary item being documented but also each item being documented completely. It is important not to leave things to assumption even if they appear to be obvious. It is not enough to say that the "Enable Low Power Mode" bit "enables low power mode". Each state of the bit should have a definition, and the bit's function should be described completely. Does setting the "Enable Low Power Mode" bit initiate low power mode or does it just enable low power mode to be initiated by some other event? Reference documentation with a high degree of completeness translates to faster time-to-market for product users and a lower support burden for product vendors.
Ease of navigation means that users can find the information they need when they need it. Users do not often read reference documentation from beginning to end, but rather look up specific information as the need arises. For this reason, reference documentation should be well organized and architected in such a way that specific documentation items can be easily found through built-in navigation aids and search functions. Cross-references must point to additional useful information with a clear path back to the starting point.
In summary, while user guides, tutorials, and videos can help users get started with a product or help in the performance of specific tasks, reference documentation remains an indispensable tool for engineers working with products like MCUs and embedded software packages. Accurate and complete reference documentation is essential for the success of engineering products and the engineers who use them.