10
\$\begingroup\$

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?
\$\endgroup\$
  • 1
    \$\begingroup\$ I think this question about deliverables has great advice about what needs to be given to completely hand over the results of a hardware related design project. \$\endgroup\$ – Kortuk Mar 8 '12 at 0:53
  • \$\begingroup\$ Photos !!!! Vast amount of information content and information density if used well. \$\endgroup\$ – Russell McMahon Mar 8 '12 at 2:24
  • \$\begingroup\$ Thanks Kortuk. That is the kind of information I was looking, but I still think that we need more information on how the project was developed and why the engineer took some decisions. \$\endgroup\$ – RMAAlmeida Mar 8 '12 at 10:36
3
\$\begingroup\$

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.

| improve this answer | |
\$\endgroup\$
  • \$\begingroup\$ There are far better online tools for this purpose than a collection of blogs. At work, we (~500 engineers) use Redmine project management for its wiki, bug tracking, and version control tools, but there are many alternatives. At school, we use Google Sites and Docs. \$\endgroup\$ – Kevin Vermeer Mar 8 '12 at 19:40
  • \$\begingroup\$ @Kevin Vermeer - The last paragraph was added as an afterthought - I haven't come across Redmine before but it looks great for this purpose in that it seems to go way beyond basic project management. A lot of tools are great in one or two areas and lacking in others. \$\endgroup\$ – MikeJ-UK Mar 8 '12 at 20:09
  • \$\begingroup\$ For any project involving design, a lab notebook should be maintained, containing written notes, highlighting why choices were made, taped in schematics, periodic witness signatures .... This sort of stuff keeps intellectual property lawyers happy, and also documents the sort of stuff to OP is talking about \$\endgroup\$ – Scott Seidman Oct 2 '13 at 16:39
2
\$\begingroup\$
  • 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?

In our company we are expected to write hardware design description documents. These are pretty straightforward: you explain at the beginning what the circuit is supposed to do, and then go into detail in each section. Every component value is supposed to be justified in some way: if you have "default" pullup or series resistors, they should be mentioned in a note in the beginning (e.g. "10K pullups and 0.1uF bypass capacitors are used unless otherwise specified"), otherwise choices for component values need to be explained. e.g. "4.7K and 0.1uF RC filter (tau = 0.47msec) used to limit high-frequency components" or "NLAS4051 multiplexer used for low leakage -- this circuit node is sensitive".

| 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.