Electronic – How make hardware documentation

EDN has a sub-site dedicated to memory.

Professor Memory may be the right place for you to learn about memory and about newer technologies.

You asked two different questions: what a contract engineer should provide and what you should have for internal documentation of a project. I'll answer the first question first. This is assuming you've been hired to design something and deliver a few working prototypes with enough documentation that the company can take it from there.

1. Schematic, obviously.

2. Board fab files. This is the zip archive of the gerber files, drill files, and a readme file so that any board house knows which files are which and any special requirements.

3. Assembly files. This includes the bill of materials (BOM), and anything else a assembly house would need to know to take bare boards and the kit and make finished boards.

   The BOM is basically a contents list for the kit and examples of where to buy anything that isn't a jellybean part. For example, something like a microcontroller must have complete manufacturer part numbers. Other parts might have only a generic part number and at least one example of a supplier part number where it can be bought. A example could be a LM324A opamp in SOIC-14 package, with Mouser part number 863-LM324ADG. Still other parts, like a 10 kΩ 5% resistor in 0805 package are jellybean parts and no manufacturer or supplier number is required. The company probably already has a preferred source for those.

   You should also include a board drawing and parts locator index. The board drawing has the designator of every part, which differs from the board because it's not always possible to put every designator on the silkscreen. The parts index gives the coordinates of every part on the board. The same coordinates should be on the board drawing. I add the schematic coordinates to the parts locator index too. Manufacturers don't care about that and don't usually get the schematic anyway, but this puts everything in one file and helps other people when hunting for a part in the schematic. There should be a separate board drawing for the bottom if anything is installed there.

4. Source code with build scripts and any proprietary tools needed to build it. After installing your software release and any third party software you specify, the customer should be able to run a single script or command to build all the software and firmware you created for them.

   Of couse the source code should contain clear and meaningful comments, answering the kind of questions someone new to the firwmare would want to know. If half of all source lines aren't comments, then your doing something wrong. Even if so, chances are you're still doing something wrong since most people write crappy comments. For example, a comment like "button counter" for the declaration of variable "bcount" is useless. You know what you mean, but stop and think about the context of someone else reading the code. Maybe "button" is obvious in the context of the device, but counter of what? Certainly not the number of buttons as the comment implies. The number of times the button was pressed? Since when? Time until the new state is debounced and declared official? What time units? Clock ticks until the button being held becomes a long press instead of a short click? Clock ticks since press to be compared against a threshold to determine long versus short press? We'll never know.

5. Firmware documentation file. At the very least, this has a section listing all the various versions, the dates they were created, and what was changed from the last version. I have my build system automatically create a new sequence number for every build within a version. When a version is released, new builds are for the next version starting at sequence 1. The sequence number of each released build is listed in the firmware doc file so that someone can identify whether a particular binary or loaded code is the official build of that version. For example, version 21 might be described as sequence 14 in the firmware doc file. If someone encounteres version 21 sequence 7, then they know that is a intermediate engineering version and there is no telling what it actually does. It's best never to let such versions out, but it sometimes happens, possibly even by accident loaded into a chip.

   If the firmware implements a communication protocol to a host computer or something, the protocol should be described here. If it is really complicated, you might put it into a separate protocol document.

6. Optional design files. Customers may want the files for the schematic and board in whatever ECAD software you use. Usually they don't, but if they ask for them they should get them. Don't try to lock the customer into having to use you in the future for changes. That is totally irresponsible in the first place. You'll likely get more follow on business by making them feel comfortable they have everything they need in case you get hit by lightning or fall down a well.

7. Theory of operation. This is also optional. Produce it and do a good job of it if asked, but don't include it automatically. That is just inviting some unsophisticated customer to think they know how the thing works and do something stupid, them blame you. Or, they think they then know enough to second guess all the details. Those that know to specifically ask for this will more likely respsect it.

Internal documentation is a different issue. Of course you have all the customer-deliverable files as described above on your computer already. In addition, I keep a log of all relevant emails edited with the fluff stripped out, and any specs, drawings, etc, the customer has sent. If you had to do some research or complicated analisys to make design decisions, then there should be design notes that describe what you did, why, what you found, and how you used that to reach the conclusions you did.