How do I document why a part was designed a certain way?
Write the reason down at the moment of the change, next to the revision it explains: one line in the revision block, and a short decision note linked from the part with the problem, options tried, test data and who decided. The drawing records what the part is; only a note made at the time records why.
Why the "why" gets lost
A drawing tells a supplier what to build. It does not say that the wall is 2.5 mm because 2.0 mm cracked in drop testing, or that the fillet is there because the first tool vendor couldn't hit a sharp corner. That reasoning usually lives in:
- a review meeting nobody took notes in,
- an email thread with a supplier,
- a chat channel that scrolls away,
- a slide deck of screenshots,
- the head of the engineer who made the call.
When that engineer, or a co-op on a four-month term, leaves, the reason leaves too.
What to record for each decision
A useful design decision note answers five things: the problem, the options considered, the decision, the reason, and who decided and when.
| Field | Example |
|---|---|
| Problem | Bracket flexed 0.8 mm under motor start torque, belt skipped |
| Options considered | Thicker plate (6 to 8 mm), add a gusset, switch 6061 to 7075 |
| Decision | Added a 4 mm gusset, kept 6 mm 6061 plate |
| Why | Gusset cut deflection to 0.15 mm in test; 8 mm plate hit the enclosure; 7075 added lead time at our shop |
| Who and when | Mechanical lead, with EE and the machine shop, 2026-03-14 |
Five lines like this take a few minutes to write and can save the next person days of digging.
Where to keep it
There is no perfect place. The test is whether the next person will find it when they open the part.
| Where | Found by the next engineer? | Survives tool changes? | Notes |
|---|---|---|---|
| Revision block on the drawing | Yes, always | Yes | One line only. Best for the "what and why" summary |
| Drawing notes | Yes | Yes | Use for requirements a supplier must follow, not history |
| Custom properties in the SLDPRT | Only if they look | Mostly | Hidden from people without CAD |
| PDM check-in comments | If you have PDM | Tied to the vault | Usually terse |
| Wiki or shared doc (Notion, Confluence) | Only if linked from the part | Yes | Room for test data and photos |
| Chat and email | Rarely | No | Where most reasons live today |
The pattern that works for small teams: a one-line reason in the revision block, plus a link or document number pointing to a longer note in a shared doc. Start from the very first discussions, keep notes light, and keep them in one place everyone can reach.
Make it a habit, not a project
Backfilling the reasons behind 300 parts never happens. Recording the reason for the next change does. Three small rules:
- No release without a reason. The release owner doesn't bump the revision until the revision block line says why, not just what.
- Capture at review time. At the end of each design review, the CAD owner writes the decisions down before the meeting ends, in the same place every time.
- Pull it out of chat. When a decision is made in Slack, email or a supplier call, paste the gist and a link into the decision note that day.
Where good habits break
These habits depend on discipline, and discipline slips in a release crunch. Revision blocks run out of space, so the reason gets cut to a few words or dropped. And the decisions made in a chat thread or on a supplier call rarely get copied over to where the next engineer will look.
Regulated products are a special case
In medical devices, ISO 13485 requires design and development records, including design reviews, control of design changes and a design and development file for each device (clause 7.3) (ISO). Aerospace suppliers working to AS9100 have their own design and development requirements. If you build for those markets, follow your quality system; the habits above still help, but they don't replace it.
When starting the next version
Before kicking off version 2, spend an hour with the decision notes for the top 20 parts by cost or trouble. Mark which decisions still hold and which constraints have changed, for example a new supplier with better tolerances, or a motor that no longer needs the gusset. That is where the next version's easy wins are, and where its repeat mistakes hide.
FAQ
How do I hand over CAD and documentation when an engineer leaves?
Have them walk through their top parts with a successor and write a decision note for each open or unusual choice. Start this weeks before the last day, not on it.
How do I onboard a co-op onto an existing hardware design?
Give them the decision notes and revision blocks for the assembly they will work on, before they open CAD. Pair them with the CAD owner for the first review they join.
Where should design decisions live: drawing notes, a wiki, or the PDM?
Put a one-line reason in the revision block, where everyone sees it, and a longer note in a shared doc linked from the part. Drawing notes are for requirements the supplier must follow.
How do I start version 2 without repeating version 1 mistakes?
Review the decision notes for the parts that cost the most or caused the most trouble. Mark which constraints still apply before changing anything.
Related questions
- How do you do revision control without PDM?
- How do I make sure my supplier builds the right revision?
- PDM vs PLM: which does a small hardware team need?
- How do I share a SolidWorks file with someone who doesn't have SolidWorks?
Sources
- ISO, ISO 13485:2016: https://www.iso.org/standard/59752.html
Kyumi is building one place for the part, for the engineers who design it and everyone who builds it. Join the waitlist.