How do you document your hardware design decisions?

Question

How do you document your hardware decisions in the design phase? How do you avoid having to ask yourself the following questions while reviewing an hardware design that you made in the past:

• Why did a choose this component?
• Why/how did I choose these particular parameters for this component?
• What does this part of the circuit do?
• What is the power dissipation through this component?
• What is the total power consumption of this circuit?
• Can I replace this component with this other one? Are there any equivalent components to this component? etc.

What is a good way to document your decisions and calculations during the design phase of a circuit? How do I get answers to the questions above without going again through hundreds of datasheet pages?

One way I could think of is to add notes in the schematic files (if your EDA supports it), but I wouldn't want to clutter the schematic with too much information.

Answer 1

I personally go the old-fashioned route: I have a design notebook where I write down absolutely everything about the design decisions I make. Especially component and value choices, current calculations, power supply calculations, everything. I also document software/firmware decisions and notes on timing and resource usage.

Each notebook has a contents page to reference a specific part of the design (power supply, etc) and all the pages are numbered.

I have considered going digital a number of times but it is nice to have my notebook out in front of me while I work and I find writing formulae digitally to be quite awkward. It's much easier to write calculations out by hand.

When preparing a spec or formal documentation for a board design, I usually refer back to my notebook as a refresher of what I did (or I write the digital documentation at the same time). Even though this may seem like I'm doing the same thing twice, I find that my notebooks are pretty much all calculation and explanation for myself, where documentation is much less verbose and much more formal and explanatory for others. As such, I don't often find I'm writing the same thing twice.

Answer 2

You could go back and update the design spec with this information. Or take the spec and create a lower level spec where you describe in more detail what you are going to do and why, ideally before you start schematics :). Then update as you go along and archive with the schematics.

---

Answering questions below: Well what we usually do is start with marketing requirements, then maybe a formal engineering response or just informal discussion. This is followed by an MRD (marketing requirements document), in word, using our template. That includes requirements, competitive analysis, market size, opportunity, estimated development cost etc. Usually this is written by a marketing person (or someone above my pay grade).

This is followed by the PRD (product requirements document) written usually by engineering, also in a word template. This describes in more technical detail what the product will do, what pieces are required, and at a high level how each one of them will function. Often we will include target performance, price, power, size and other metrics here.

That's followed by detailed functional specs for each of the sections. Some design work is actually done here well before it's put into the schematic. For example power will be calculated, parts will be selected, and a lot of research done. This is the place we would document any non-obvious design decisions.

Finally we'll get to the schematics which is the easy part at this point because a lot of the hard design work was done in the specification stage. Where it should be done in my opinion :) If something changes during the schematic stage, for example we figure out something won't work or a marketing person comes running down the hall saying it needs to be red now instead of blue, then we will go back and update the specs.

All the specs, PRD, MRD are kept in SVN with links to the docs on a internal wiki. A change to spec will result in an update to SVN and a notification to interested parties. You could of course just keep it manually in a shared folder somewhere.

That's more or less my process, I feel like you might want to document every tiny decision made about a design and we definitely don't do that. Not saying you shouldn't, I could see where it would be helpful. I guess we usually document the how and not the why all the time.

---

Ok maybe I should have also addressed each question :)

If you are making calculations, in excel maybe? Or on paper and you think the results and the method are important to the understanding and design of your circuit, then you should include those in the appropriate section of the design specification. Even if that means taking a picture of your hand drawing :)

Why did a choose this component? I think the functional spec is a good place for this, no need to go crazy but just a simple line or two about what it's advantages were. I'd reserve this for critical components, I don't think you want to describe why you chose a pull-up resistor for instance.

Why/how did I choose these particular parameters for this component? Combine this with above.

What does this part of the circuit do? This would be part of your functional spec, if the circuit is important enough to warrant this question it should have it's own section of the spec.

What is the power dissipation through this component? If you're talking power supply put this in the power section, also I like to note this on the schematics. Really though all my parts come from a database and the schematic is direct linked to them so we can easily see the parameters, datasheet etc. But if you just have a print out it's nice to know some of this.

What is the total power consumption of this circuit? I think this belongs in the power supply section of your specification.

Can I replace this component with this other one? Are there any equivalent components to this component? etc. This I think belongs in your BOM or whatever process you use for manufacturing. Alternate parts are to make sourcing easier. Again for us this is all coming out of a parts database.

Answer 3

I do a lot of quick-turn design and I have to say: annotating the schematic is by far the most convenient thing. It's rare for any of my designs to be more than 2 or 3 A4 sheets, so the amount of design decisions is limited. A lot of design decisions are pretty much automatic; I don't need to list reasons for every single part. Just one or two main parts and maybe some filter or sensing passive sizing. The rest is immediately obvious to any experienced design engineer.

As for your last question: alternative parts are generally not a design decision but a sourcing decision, and as such it's part of your sourcing workflow. In my case, alternative parts are in my part properties and get sourced automatically if stock runs out on the primary part or source.

For larger designs and for system design, I tend to use Google Docs with a design document template.

In summary; I am personally of the opinion that a compact workflow will pay off in the end. Having lots of separate files with design information (separate system design, design decision documents, sourcing documents, all separate from your basic schematic and layout files) causes a lot of (mental) clutter and requires context switching every time you want to review a design decision. Having everything in one place works well. If your schematic starts looking cluttered this is not a problem with this workflow but rather means you should probably compartmentalize your design better, use more sheets or use larger sheets.

Answer 4

I have often used keynote (you may also choose to use PowerPoint). This has the advantage of allowing screen caps of simulation software such SPICE GUIs and such.

Really key for me is the ability to drop in snippets from data sheets and mark them up so the relative importances in my design decisions show up. I can also include photos of early circuit boards or breadboards, and links to articles I used to make design choices.

I also find that I tend to want to do math and drawings using pencil on paper. So I take a photo with my phone and drop it in the keynote without retyping. Sometimes for short equations I may use LaTeX and drop that in.

I also can include plots drawn by scientific software such as octave.

Nowadays, especially for computationally intensive tasks I may choose to do some of this work in IPython notebooks, but I haven't specifically done that for circuit designs, just for physics computation.

Finally, Keynotes/Powerpoints are easy to pretty up for others and export as pdf for distribution to non/less technical people.

Answer 5

For many of my smaller projects, I've generally been placing a simple green label and border around sub-circuits. For larger projects, some eCAD software allows you to build from a block diagram down, where each sheet further describes a single block. There's an art to decomposing any problem, and managing the tradeoffs (that's engineering IMHO). Where there is clearly some analysis for choice of components such as analog filtering, I'll note the cutoff frequency and filter type (e.g. Low-Pass Filter (f_c = 100Hz))

Common blocks I run into time and again include:

• Power Management (voltage regulators, reverse-polarity protection, TVS diodes, power switch, bypass caps, etc)
• MCU (microcontroller, programming header or pads, chip bypass caps)
• Indicators (e.g. LEDs, EL wire, 7-seg display, vib motor)
• Sensing for a particular feature (e.g. Current Sensing, Touch Sensing, GSR, Activity, Environmental Sensing, etc)
• Debug Comms (ferrite bead, USB, I2C, UART, SPI, some way to get info out)
• Radio (all the support components for many radios)
• Video (all the support components and chips for a camera)
• External Storage (e.g. External Flash, EEPROM chip to store settings, etc)
• Any other feature unique to your design

With these sub-blocks clearly organized and labeled, I can consume a schematic in usually less than a couple minutes.

Answer 6

Place engineering notes on the schematics and if needed create more sheets. I always place engineering notes on all of my schematics because in my world I may have to re-visit 1/2 baked designs for a time period then put it on the back-burner again while I pick-up another design; very fluid design flow. These EE notes help me and others re-embrace the design intent with little effort. I also use different colors of text/graphics to indicate the importance or context. Example below...

Answer 7

I keep a design notebook, and carefully document needs/wants. For the earliest prototypes, I'll go through part selection, taking notes on all the real decisions. For subsequent changes, I use a fairly formal FMEA process, documenting which need is not being met so as to justify a change -- because obviously, if there is no unmet need, there's no need for a change!

If I'm rigorous enough about this, I can track every design change (hardware, software, mechanics) to a need.

All versions of all things are tracked using subversion.

This can be a substantial component of a Design History File, which is a must for the FDA.