Electronic – How make hardware documentation


I'm building some slides for my class about how we should document the hardware we are developing.

I'd like to list the documents we should make when building some hardware. I was inspired at UML software documentation, which brings lots of document types for almost every situation.

From my experience and research, lots of projects only have the schematics, the layout and the bill of materials. I think that we should also add information about the motive (requirements) that lead us in choosing one microcontroler and not the other. There are also some information regarding the layout that we just don't write, as special component position that should not be changed.

That being told:

  • How we should document our hardware?
  • Which are the important document you wanted to have if you need to make some improvements/alteration on someone else hardware you have never seen?
  • How organize these information in a clear way?

Best Answer

I strongly agree with your third paragraph. Apart from the obvious things like schematics, BOMs etc there are the less tangible things like, as you say, why you chose a particular component and just as important, why you didn't choose a perhaps more obvious component.

Now I might be showing my age here but I still like to use a hardback ruled log book to record my thought processes & design decisions - even the wrong ones. If someone in the future tries to replace a component with a more 'suitable' one or moves a track on the PCB, my notes might tell them that I've already been there and burnt my fingers (perhaps literally!).

I always number the pages and allow a few pages at the front as a table of contents. You can also document such things as calculations of power dissipation, tolerances, timings etc. (this habit comes from my days in the aerospace industry where keeping a log book was mandatory). Of course you could always put this information in a WP document but I'll stick to paper!

Circuit descriptions might also be appropriate where unusual (especially analogue) circuits are concerned. I would treat these like software comments to document any unobvious circuit or components functions. Schematics, like software should be 'self-documenting' as far as possible but sometimes this isn't enough.

A more up-to-date alternative, especially in an educational environment, might be to have a project website. This could be arranged as a collection of blogs for each discipline - hardware design, pcb layout, software etc. The blog nature would allow contributors to show their thought flow and document the ongoing progress of the project whilst other pages could be more formal (progress Gantt charts, test results etc). You could even add meeting minutes and action lists. Hyperlinks make cross-referencing easy and now we have MathJax so even design equations are simple to insert.