Ask HN: How do you document your hardware projects? I'm curious to learn how others are documenting their hardware projects? I tend to use a combination of OneNote and Google drive, but I think there must be better alternatives. I've seen a number of others documenting their hardware projects with GitHub, and it would be interesting to learn if people have had a good experience and if they have guidelines/workflows to share. |
We currently use antiquated systems, or bad software based on antiquated systems.
My approach - don’t rely on software. It’s a mentality, not a software. Your CAD should be organized in a future proof structure. Your analysis should reference the hardware by diagram. You should be able to easily find the analysis with nothing more than a hunch. Your drawings should be organized and the numbering should make sense. Create a part numbering schema that gives some information more than just the part number.
Ask yourself every day - if someone asks me where the work I did today is, would I be able to quickly find it?
- Designing a UI for resolving merge conflicts is non-trivial and a lot of the visual cues git diff viewers use to highlight conflicts (colors, marker text, etc.) don't translate well into a CAD viewer
- The Autodesks and Bentleys of the world work in proprietary binary files so any solution would only work for one vendor, and sometimes only one flavor of one vendor
I will often mark pages as 'public' and commit the modified files to my Github repo - which triggers a website update workflow to my docs.mypersonaldomain.com.
If I want to document further and for whatever reason it is not something that looks great on Logseq, then I pull the data out and use whatever. Usually Github, as I typically want as much content I've worked on to be visible to the world.
https://allspice.io/post/git-for-hardware-commit-best-practi...
The biggest changes I've made recently are leaving notes inside the schematic (so I can't miss them) and keeping local copies of every datasheet and app note that I need.
Also a lot of notes in the schematics/layout as well, utilizing layers. Overall I'm pretty satisfied.
But nothing prevents such a system from working with arbitrary files, as long as there is a tool to create a "patch" or a "diff" (that is, a description of a change) and a tool that can apply such "diff". Git does have a mechanism to plug in both of these tools, depending on the file type.
I have a very vague idea of what CAD files are internally, but I suppose they are some kind of a database, and they are not colossal (unlike e.g. video files or such). They certainly could use this mechanism to allow tools like git (or hg, or maybe even perforce) be used in workflows involving CAD files, with human-understandable and reviewable changes.
I wonder if someone has ever tried that. I can't be the first person to have this obvious idea.
The main part I worked on was to be able to do exactly this (not for CAD files specifically, but including those). It was a very difficult, but rewarding, problem to solve.
I'm more interested in tracking and versioning edits to KiCAD schematics, for instance.
I haven't found anything in the usual markdown, git, wiki suggestions that the tech crowd here gives that works as well. Inline images doesn't do this. Too bad because I really want a self hosted open source solution.
The best other option is a decent pdf editor because you can paste in and annotate and save without collapsing layers.
I am trying pdfxchanger viewer lately with the watermarks for free editing capabilities but might actually buy the license for the editor. This syncs via nextcloud or boox to my tablet but has limitations.
<project-repo>/README.md defines problem, requirements, interfaces and any notes on structure and approach investigated or selected.
<project-repo>/<module>/v7/ alternatively <project-module-repo>/v7/x
This macro approach allows straightforward onboarding of new staff whilst effectively firewalling irrelevant/unauthorized information. This last bit is really helpful with a revolving door of engineers on a long and complex project. Use of git also allows leveraging third party dates to prove independent development in the unlikely case of IP litigation, and provides a clear design history for patent applications.
Within individual modules things like prototype images, videos, test results, any relevant supply chain information and so on are readily stored.
I tend to segregate PCBs and firmware from mechanical, so a conceptual hardware module may have one repo per board, one repo for overall mechanical design, and one repo for firmware. For the PCB repos, a lot of info is testing related, even right down to scope shots, PSU logs during bringup, state transitions, software test results, etc.
Efficacy: Current project (8 years) has dozens of modules, extreme complexity, 10,000 parts, evolving international supply chain. Using this approach, however, I have been able to manage things effectively.
Saves as markdown and can be processed to other formats.
Also allows writing as you work.
For step by step stuff, I’d lean towards logseq as the UI but sharing a folder inside an obsidian vault folder. Logseq is more at the bullet level which can be more useful in certain cases
Lots of videos on your tube on this setup to allow you to access the best plugins from both systems.
With other apps, I would still spend so much time thinking about where to put my notes when it's already difficult for me to take notes and organize things in the first place. I would end up with what was essentially a digital junk drawer. It was all there, but it was a scavenger hunt when I needed to find something and nothing was ever connected.
With Logseq, I started using the journal, tagging and linking as needed as I write. I don't ever think about where to put anything. Although I occasionally create separate pages, I'm mostly in the journal. The tags I add to individual notes become their own pages that are sort of a hub containing every reference. Sometimes I go into those hub pages and add more substantive documentation than the journal references. After several days, I saw this network of information starting to come together. It's like being able to make a contemporary recording of my brain and then reference it later.
I've tried many methods over the years, but in the end, the local Wiki serves my needs the best.
The documentation is stored similarly in MD files splattered throughout a "notes" folder synced between my devices.
It's mostly unorganized chaos.
http://emsoftware.com/products/docsflow/ for GSuite to Indesign.
I did set things up in Notion, but software is already documented in Git, so now we add in our QAS documents for each pull request.
Granted, these are "personal" (still revenue generating) projects and the bus factor is 1, but it works for me.
I used my sweet label maker till I realized that it prints on heat sensitive paper and the label eventually fade out.
If done properly it can be setup to automate a lot of the tedious work, making the process of designing things much smoother.
If done improperly it adds even more nonsense to all the stuff you already are doing, so it makes the process If desiging things twice as hard and confusing.
The key - have people that have actually used it to design things architect the setup, not professional managers.