Im soon to be developing a product on my own, for possible or sale or given away(open source as such). But I am struggling with the "internal" documentation that I should produce.
- What documentation needs to be produced with in companies for sharing with new people joining the project? Is there like one document that explains the development of the project from initial idea through to the designs for the specific final product.
- What have other professional engineers had to do for their documentation in the past on their projects?
I understand that documentation varies from company to company but I'd like to start working with good practices and writing good documentation about my designs so that I am used to it when I start working.
I have read the following questions:
- What should a contract Electrical Engineer Deliver once a project is complete?
- How make hardware documentation?
But these refer to specific parts in the designing of a product. Such as the first one what to produce once it has been designed, and the second refers to the development of the hardware. I'd like to know about documentation at the other stages of the design process.
Best Answer
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.
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.
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.
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.
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.