43
\$\begingroup\$

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.

\$\endgroup\$
  • 1
    \$\begingroup\$ Who is going to see these details? Are they just for your reference or will they be seen by others? \$\endgroup\$ – stanri Feb 9 '15 at 15:26
  • \$\begingroup\$ @Stacey The documentation is intended both for me and other designers to read. I'd like to make most of my future designs open source and it's very important that they are properly documented. \$\endgroup\$ – m.Alin Feb 9 '15 at 15:33
  • 10
    \$\begingroup\$ @Stacey But really.. what's the difference? After a while you'll look at your own design as if it's the first time you see it.. \$\endgroup\$ – m.Alin Feb 9 '15 at 15:36
  • 2
    \$\begingroup\$ The difference is in the way that the information is presented. A formal document explaining every decision you made in a professional tone is going to be a lot more work than quickly jotting down a formulae and note about the values you chose. Additionally, if someone else is going to see the notes, then the fact that they're digital is important. \$\endgroup\$ – stanri Feb 9 '15 at 15:39
  • 4
    \$\begingroup\$ OMG I love this question. (sorry I know its not really helping, but this is something I'm working on right now, so this is great). Carry on. \$\endgroup\$ – efox29 Feb 9 '15 at 16:39
15
\$\begingroup\$

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.

| improve this answer | |
\$\endgroup\$
  • \$\begingroup\$ Agree completely on the formulae issue, but I stopped using paper notes about 5 years ago. Typing is far easier than writing, and has all the usual electronic text benefits - searchable, sendable, backupable, etc. \$\endgroup\$ – markt Feb 9 '15 at 21:15
  • 2
    \$\begingroup\$ Some of the most impressive/important design notebooks of our times: computerhistory.org/collections/fairchild. One significant advantage to a paper logbook/notebook is drawing. It takes significantly more effort to draw/sketch things on my laptop (though it's easier on an iPad - my wife for example keeps her design notes on her ipad). I tend to think graphically so I do a lot of my designing by drawing block diagrams. \$\endgroup\$ – slebetman Feb 10 '15 at 4:04
12
\$\begingroup\$

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.

| improve this answer | |
\$\endgroup\$
  • \$\begingroup\$ I realized that I have to document my design (hence the question), but I don't know of a good method to do that. Do I write my notes in a text file, do I put the notes directly in the schematic, do I write the notes on paper and then scan them? How do I keep the design decision notes synchronized with the design and what should the notes really contain? What's the documentation method that work for you? \$\endgroup\$ – m.Alin Feb 9 '15 at 14:49
  • 1
    \$\begingroup\$ @m.Alin SHG seems to operate like me, and has a spec document that is done before working on a schematic. This document should have detailed requirements for the circuit, information on the overall system, reasoning behind major decisions, etc. This documents your thought process and lists the requirements you can then take to design your schematic. This is the way to go in a professional setting, but you can get away with notebooks and the like if you're doing the design at home. I usually keep a folder on my work server with \$\endgroup\$ – I. Wolfe Feb 9 '15 at 15:38
  • 1
    \$\begingroup\$ Ran out of room... -with the spec document, any testing documentation, any block diagrams of the overall system, datasheets for any critical parts, etc. That's all in one subfolder (the planning/specification folder) in the project folder. In a separate folder I'd have the schematic, pcb layout, and any relevant assembly/manufacturing documentation. Ideally you'd like for someone to be able to get all the info they need from one document, but sometimes there's no getting around needing a datasheet or detailed testing info/calculations. \$\endgroup\$ – I. Wolfe Feb 9 '15 at 15:40
  • \$\begingroup\$ added some comments on our process inline \$\endgroup\$ – Some Hardware Guy Feb 9 '15 at 15:59
  • 5
    \$\begingroup\$ +1 for using version control for critical documents. Everyone should use it, even a single, self employed engineer. \$\endgroup\$ – Lior Bilia Feb 9 '15 at 16:11
5
\$\begingroup\$

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.

| improve this answer | |
\$\endgroup\$
  • 3
    \$\begingroup\$ It is usually better to have a spec document, at least in a professional setting. For instance if I want to know why I chose a fuse value, it would be good to know that my output draws 700mA for 50uS and then 300mA for 3s. This information just clutters a schematic where all you really need to put is the fuse rating, but might be needed at some point. There's also circumstances where I have had 6 servos running off of one regulator, and I need to know how many motors will run simultaneously. Again something needed, but not on the schematic. \$\endgroup\$ – I. Wolfe Feb 9 '15 at 15:04
  • 1
    \$\begingroup\$ Of course, opinions will vary. All I'm saying is that with 200+ designs under my belt I find that this works really well. 'Professional' doesn't need to mean strict protocol and methodology; for relatively small designs (which is the majority of what I do) this works well. Larger designs and especially collaborative design (which is very rare these days, even stuff like Raspberry Pi is designed and laid out by the same one guy) does require a bit more boilerplate though. \$\endgroup\$ – user36129 Feb 9 '15 at 15:30
4
\$\begingroup\$

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.

| improve this answer | |
\$\endgroup\$
3
\$\begingroup\$

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.

| improve this answer | |
\$\endgroup\$
3
\$\begingroup\$

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.

| improve this answer | |
\$\endgroup\$
3
\$\begingroup\$

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...enter image description here

| improve this answer | |
\$\endgroup\$

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.