Documenting Your Design

Introduction

A working breadboard prototype is not a finished design if nobody else can rebuild it. Documentation is part of embedded system architecture — the same way a pin map belongs next to your schematic. As a student, you document so teammates can review your work, coaches can assess it, and you can resume the project after a break without reverse-engineering your own wiring.

This article covers the four documents most prototype projects need: block diagram, pin map, wiring diagram, and bill of materials (BOM), plus requirements traceability to show your system meets its goals.

Good documentation takes less time when you update it as you build, not in a panic before the deadline. See the overview in Embedded system architecture.

Block diagram

A block diagram shows major subsystems and data flow at a glance — no every wire, just the big pieces.

Include:

• Microcontroller
• Sensor groups
• Actuator groups
• Power supply
• External systems (server, phone, PC) if connected

Draw it on paper, whiteboard, or export from your diagram tool. One page is enough for most student projects.

Pin map

A pin map is a table every firmware and hardware author needs. It is more detailed than the block diagram.

Suggested columns:

Update the pin map when wiring changes. Your firmware drivers should match this table — if the map says pin 25 for the LED, the driver uses 25, not a magic number buried in the main loop.

Wiring diagram

A wiring diagram shows how components connect on the breadboard or PCB. It is not a photo of your desk — it is a deliberate drawing made with a tool intended for electronics documentation.

Tools

Quality checklist

• Show power source, Vcc, and GND explicitly
• Route wires horizontally, vertically, or at 90° — avoid diagonal lines over labels
• Label every part with correct values (220 Ω, DHT22, your exact MCU board model)
• Red wire for Vcc, black for GND; use a third color if you mix 5 V and 3.3 V rails
• Power components from breadboard rails, not star-wired from MCU pins where possible
• Do not hide part numbers or LED polarity under other wires

Common wiring diagram mistakes

1. Missing power supply or ground symbol
2. Unlabeled parts or wrong resistor values
3. LED reversed (long leg = anode, short = cathode)
4. Wrong MCU board variant drawn
5. Wires covering labels you need to read
6. Wrong sensor model (e.g. DHT22 drawn as DHT11)

Add a short introductory paragraph above the diagram in your project docs explaining what a wiring diagram is and what this specific diagram shows.

Videos — Fritzing and circuit tools

Fritzing Tutorial - A Beginners Guide to Making Circuit & Wiring Diagrams

Create Arduino circuit and code — Circuito.io

Also try circuito.io for auto-generated wiring from a part list.

Bill of materials (BOM)

A bill of materials lists every part needed to build one unit, with enough detail to order replacements.

Required columns

BOM tips

• Include everything in the wiring diagram: MCU, breadboard, jumper wires, resistors, sensors, power supply
• Parts sold in packs (LEDs, resistors) — divide pack price by count for unit price
• Fill every cell; no empty fields
• Optional extras: tolerance, connector type (M/F), wire length, datasheet URL

Add introductory text above the table explaining what a BOM is and that it matches your wiring diagram.

Videos — bill of materials

What is a Bill of Materials (BOM)? Why is it Important?

Bill of Materials for a prototype or low volume electronics

An Intro to KiCad – Part 9: Generate BOM and Order Parts | DigiKey

Common BOM mistakes

1. Missing jumper wires, breadboard, or power source
2. Vague descriptions ("resistor" without value)
3. Non-clickable URLs
4. Missing subtotal column
5. Listing whole pack price instead of per-unit cost

Requirements traceability

Requirements traceability links what the system must do to evidence that you built it. For each requirement, record:

1. ID and description — what must be true
2. Priority — e.g. MoSCoW (Must / Should / Could / Won't)
3. How the architecture addresses it — hardware, firmware, or connectivity choice
4. Compliant — yes or no
5. Evidence — code snippet, screenshot, measurement, demo link

Example:

Peer review helps: ask another student to check each "yes" against the evidence.

How documents fit together

These artifacts should agree: every part in the diagram appears in the BOM; every pin in the map appears in the diagram; every "Must" requirement has proof.

Relevant topics

• Embedded system architecture
• Hardware architecture
• Basics of electronics
• Lab tools for prototyping
• Reading datasheets
• GitLab Markdown tables

Starting points

1. Create a pin map template in your repo before the first wire.
2. Open Fritzing (or your chosen tool) on day one of wiring — update as you go.
3. Add a BOM row each time you place a new component on the breadboard.
4. Write requirements in plain language before coding; add a compliance column later.
5. Ask a peer to rebuild from your diagram only — gaps show up fast.

Focus points

• Document while building — retrofitting diagrams after teardown is painful.
• BOM matches diagram — if it is wired, it is listed, with specs and price.
• Labels on everything — in Fritzing and in the pin map; no "mystery GPIO".
• Evidence for every Must — "it works on my laptop" is not proof without a reproducible step.
• Introductory text — each diagram and table gets a sentence on what it is for.
• Version your docs — commit diagram exports to Git when the breadboard changes.
• Peer review — another pair of eyes catches missing pull resistors and BOM gaps.

Key points

• Documentation is a layer of architecture, not paperwork after the fact.
• Pin map + wiring diagram + BOM let others reproduce your prototype.
• Use proper tools (Fritzing, KiCad, etc.) and follow wire-color conventions.
• Requirements traceability connects goals to design choices and proof.
• Keep all documents consistent with each other and with the code.