Keeping your design documentation organized is a simple way to make yourself more effective as an engineer and teammate. Here’s a simple way to organize your KiCad projects on your PC, shown in tree format:

your-project-name/
├── arch
├── cad
│   ├── your-project-name
│   └── lib
├── change
├── docs
├── errata
├── fab
│   ├── asm
│   ├── draw
│   └── pcb
├── pdf
└── releases
    ├── staging
    └── v1p0

Each of these directories stores a different element of your KiCad project. Here’s what each directory is meant to store.

your-project-name/

This is the root directory of your project, containing all the subdirectories and files related to your KiCad project.

arch/

This directory is typically used to store architectural or design files that outline the overall structure and specifications of the project. It’s a good place to store design documents, requirements and specifications, or high level block diagrams of the system. This is typically where you want to start designing your system!

cad/

This directory contains the CAD files related to your project.

  • your-project-name/: This subdirectory holds the main KiCad project files, including schematics, PCB layouts, and other design files. This is the directory KiCad would create when you start a new KiCad project.
  • lib/: This subdirectory contains custom libraries used in your project, such as component symbols, footprints, and 3D renderings like STEP files. Typically, these are either symbols/footprints you create yourself, or collateral imported from a third party source like SnapMagic, Ultra Librarian, or another CAD symbol service.

This directory allows each user to use their global KiCad symbol and footprint tables, but import additional components in such a way that they are kept bundled into the project directory. It is meant to allow you the best of both worldds: access to the standard KiCad global symbol and footprint libraries, in the default location on your computer, plus local storage for any additional libraries or components you need to create or import into your design.

change/

This directory is used to track changes made to the project. KiCad doesn’t have a great system for tracking changes internally in schematics or PCB files. Instead, it’s generally easier to keep an external change log of schematic or board revisions. Here’s a short example of how to write a changelist:

#2024-05-31
- Changed all resistors to 0402 footprints instead of 0603
- Swapped UART_RX and UART_TX pins on U3; these were backwards

#2024-05-27
- Added 2k pullup resistors to I2C bus 2

If you’re keeping these changelogs as markdown inside a git repo, you may choose to put the most recent changes at the top of the file, so that the most recent changes are rendered first in your git web client. However, this is just a convention - it’s absolutely acceptable to append changes to the end of the file if that is your preferred convention.

docs/

This directory stores documentation related to components in your project. This is a store for component datasheets, reference manuals for programmable devices, user guides for EVKs, or other procedural notes or references related to the project. Note that

errata/

This directory is used to document known issues, errors, and their workarounds. It helps keep track of any problems encountered during the project and their resolutions. One errata file per board revision is normal - e.g. rev1.md contains the errata from board revision 1. That way, it becomes easy to check against a board’s errata when designing the next revision. The errata file from a prior revision becomes a checklist of fixes to ensure the next revision does not exhibit the same bugs!

Note that this isn’t the same as a bug tracker, and isn’t meant to be replacement for bug tracking software. It’s meant to serve as a record of board errors, and, if possible, rework guides that explain how to fix those errors in rework.

fab/

This directory contains files and documents needed for fabrication and assembly.

  • asm/: This subdirectory holds files related to the assembly process, such as pick-and-place files, assembly drawings, and component placement information.
  • draw/: This subdirectory contains drawings needed for fabrication, including mechanical drawings, assembly diagrams, and other relevant documents.
  • pcb/: This subdirectory stores files needed for PCB fabrication, including Gerber files and drill files. It’s also a good candidate location for files like GenCAD or other CAD files your fab/assembly house may ask for.

pdf/

This directory is used to store PDF versions of various project documents. PDF schematics, PCB prints, and assembly drawings are the most common exports. These files are useful for internal review, and confirming design intent to external fabrication partners.

releases/

This directory contains files related to project releases and versions.

  • staging/: This subdirectory is used for preparing files for an upcoming release. It may include files that are in the process of being reviewed or finalized.
  • v1p0/: This subdirectory represents a specific version of the project (version 1.0 in this case). It contains the final files and documentation for that release, making it easy to reference or distribute.

Conclusion

This structure helps organize all the necessary files and documents for a KiCad project, ensuring that everything is easily accessible and well-categorized. In addition, there is a wealth of tooling available to help generate some of these output folders and documents. We’ll cover those tools, and how to use them, in a future post.