By Richard Quinnell, editor-in-chief
Ask most electronics developers what they do for a living and, most of the time, you’ll get an answer describing the kinds of products they develop. But the truth of the matter is much more mundane. The most important deliverable at the end of product development is not the hardware prototype or the application software. It’s the design documentation, and getting it right can pay huge benefits down the line.
Professional developers are those who create products destined for manufacturing, distribution, and sale. In most cases, these products will also require field maintenance, bug fixes, upgrades, and user support as well as spawning product variations and often having at least part of the design copied and re-used in a totally new product. None of this can readily happen if the original design is not properly documented. Sure, it’s possible to reverse-engineer something without having any design documentation and then move forward to engage in these activities. But even then, the first outcome of the reverse-engineering effort is basic documentation of the existing design.
The way most projects go, designers move on to something new once development is complete, leaving the responsibility for all of those follow-on activities to others. But even when the original designer is called in to help, chances are that much of their original design thinking has been forgotten. So in either case, having decent documentation will prove invaluable in speeding the effort.
What constitutes “decent” documentation, though, is a bit subjective and subject to the development team’s cultural biases. Furthermore, there are many kinds of documentation that need to come out of a development effort intended for production, including, but not limited to, user manuals, test procedures, product descriptions, and design specifications. This truth leads to the first of the 10 key elements that constitute useful documentation:
1. Target an audience. The details of what a document should contain will vary with the document’s purpose, so the first thing to know is who the documentation is being written for. Ask about (or anticipate) their information needs and what they will be using the documents to help them accomplish. The answers to those questions can help you select what kind and how much information to include in the document. In this article, I am assuming that we are talking about preparing the system documentation needed to help a future developer adapt, expand, or apply your design to meet new requirements or to correct unexpected behaviors (i.e., bugs). Much of the raw information asked for in the following tips can be captured in real time, such as in notebooks, but will still need to be organized and presented in ways that meet a specific audience need once the design phase is complete.
2. Maintain a task focus. Focus your documentation on helping the reader accomplish their anticipated goal. One way to do this is to ask yourself what you would want to know about the design to help expedite your ability to make changes without introducing unintended consequences, then provide that information. This will require more than simply stating what was done; it will need a description of the reasons behind design choices.
Image source: Morguefile.
Hardware documentation
3. Describe hardware function and intent. For a hardware design, provide the document reader with information that can help them understand both the details of a design and its overall structure and operation. Many developers choose, for instance, to organize schematics using dotted lines to encircle functional blocks or subsystems (such as a modulator, power management, or signal conditioner) or place them on individual pages and provide writeups that address these blocks individually. They then prepare an overall diagram of the design using these same blocks and describe how the blocks operate as an ensemble to provide a system overview. The individual block writeups are particularly useful to developers seeking to re-use segments of the design in something new.
4. Describe interfaces. Detail the key electrical and timing characteristics of signals passing into and out of a functional block, including power. Again, this facilitates later re-use of a hardware block, but it also helps during debug and test by indicating what the key signals should be like. If there are critical timing requirements (such as setup and hold times) or limits such as load impedance or voltage/power levels, be sure to include these. Some developers annotate their schematics directly with notes indicating the signal lines or specific components involved to provide such information.
5. Discuss component choices. In many cases, why a specific type or value of component was chosen is as important as the component’s placement in a circuit. Is there a reason to use a wire-wound resistor instead of a carbon composite or a ceramic instead of a polyester capacitor? Not every component needs justification, but make a note of such choices and the reasons behind them when they are of significance. Similarly, if there are power ratings, frequency characteristics, dimensional requirements, or any other vital reasons for a specific choice, note them. This will prevent problems down the line should someone be tempted (or required) to make a substitution for convenience or to save cost. Such notes can be included in the bill of materials or directly on schematics as seems most appropriate.
6. Include relevant calculations. In addressing issues such as power dissipation, frequency response, protective circuits, time constants, impedance matching, gain settings, and the like, designers typically need to calculate the appropriate values. Preserving these calculations for later developers to review can greatly aide their understanding of a circuit’s function and operation, especially if they want to modify one or more of these characteristics. The most common way of preserving these calculations is in a design notebook (or online document) that developers keep as a running log of their thinking while creating their design. The notebook itself is most useful to the original designer for their own future reference, but a summary of critical calculations should also be included in system documentation to guide any future outsider. A notebook makes it easy to replicate that information into another document, though, without having to go through the calculation again.
Image source: Pixabay.
Software documentation
Many of the above suggestions apply to software documentation, as well, but with a bit of a twist. Software does not need to be fabricated, so there is no need to anticipate possible substitutions, and the final prototype — the source code — can also form much of its own documentation. Just not all.
7. Describe higher-level architecture. Well-commented source code is helpful for later code developers trying to follow the logic and implementation of individual functions and procedures, but there also needs to be higher-level descriptions that describe how these pieces fit into the overall system. These descriptions can be in the form of flowcharts, state diagrams, or text, and their purpose is to let developers see at a glance where making a change within an individual code block might have an impact on other parts of system operation.
8. Describe variables. Along with comments, code blocks should contain a summary description of the variables that the code uses, their purpose, their type and dimension, and their expected value ranges. Descriptive names can help in clarifying variables’ purposes and are even more useful in helping a developer follow the code’s logic but should not be the only descriptions provided
9. Strike a balance. Einstein is credited with saying, “Make things as simple as possible, but no simpler.” Code documentation is a perfect target for that advice. Long, verbose descriptions that tell a developer more than they need to know are not only time-consuming to create and difficult to maintain as the code evolves, they are also difficult to read and absorb. Striking the right balance between completeness and brevity can be challenging but worth the effort.
10. Collaborate. One way to help strike the necessary balance is to work with others on creating and reviewing documentation. It is altogether too easy for someone describing their design thinking to forget that others have not been living with that design for weeks and months. Having someone else look things over as though they were to be the next person working on the design will help to ensure that all of the needed information is present and sufficient. Alternatively, working with someone skilled at creating documentation can help capture design intent.
All of this documentation activity, by any estimate, requires a considerable amount of effort , but it can pay off handsomely later when the design needs to be updated, modified, cannibalized, or fixed. The effort also represents one of the most significant differences between amateur/hobbyist designs and professional ones. For a professional, creating a system that works is not their end goal. The true goal is to put into the hands of others a package that allows that design to be efficiently manufactured, installed, maintained, and evolved without the designer’s further involvement.
To learn how to design and develop motor control applications with NXP MagniV MCUs using model-based design, register for the free webinar, sponsored by NXP
Advertisement
Learn more about Electronic Products Magazine
