Ask HN: How do you document your hardware projects?

[jopizio]

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.

[em0sh]

Mechanical Engineer here - this is the million dollar question.

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?

[letitbeirie]

Non-software engineering has needed a git-like version control system for decades now but there are two giant hurdles:

- 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

[iancmceachern]

Do you use a PDM system?

[em0sh]

At work. I think it’s not very good most of the time.

[iancmceachern]

It's all in the setup.

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.

[Pulz]

I use Logseq for all my note taking and documentation.

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.

[RB333]

Git commits for hw -

https://allspice.io/post/git-for-hardware-commit-best-practi...

[wibbily]

Poorly, usually. Markdown files everywhere, occasionally a google doc if I'm away from the laptop. Usually hardware projects will end up in a git repo, but mostly for the benefit of whatever firmware I'm writing around it - if there's any specific Kicad integration with version control, I wouldn't know.

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.

[warble]

Kicad stores as XML as you probably know and is fairly human readable, so I use git on the project folder directly. Works great, although manual merges are a little involved, but I'm never in that position.

Also a lot of notes in the schematics/layout as well, utilizing layers. Overall I'm pretty satisfied.

[nine_k]

Just thinking aloud. Change-tracking software like git works with "patches", that is, changes applied to a source file to produce the changed file. They are hardwired to work with text files like source code, with short lines, and with line-oriented changes.

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.

[JohnFen]

A lifetime ago, I worked on a large project that was never completed because Google released Wave, which addressed the same problem. Wave did it in a less useful way, but my employer (understandably) didn't want to go toe-to-toe with Google and so abandoned it.

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.

[BillyTheMage]

I think version control like this would work great with programmatic CAD like OpenSCAD

[lincoln20xx]

Git works great with text-based code-cad. My personal favourite flavor is build123d, which is based on cadquery.

[nine_k]

Since OpenSCAD uses basically source code format, it already does.

I'm more interested in tracking and versioning edits to KiCAD schematics, for instance.

[bgnn]

I think you are describing something similar to Perforce Versic [1]. I use this at work to diff schematic or layout. The ugly thing is: it's perforce.. I wish there was an open source alternative.

[1] https://www.perforce.com/products/versic

[fanf2]

KiCAD’s storage format is s-expressions, so it works OK with git (better than binary file formats). However I have not tried to merge concurrent edits by multiple people; I suspect if there is any conflict you are basically out of luck.

[533474]

CSG is not as useful as BReps

[snailscale]

This is what allspice.io does

[zeagle]

Onenote has the advantage of a canvas and taking screenshots then annotating or drawing over these. Then you can edit resize canvas drag things etc as you re-edit. Mix than in with tables, flagging, check boxes and mobile device support just works and is great.

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.

[jopizio]

This feature to add annotations directly onto the canvas is the main reason I've continued to use OneNote (despite its limitations like lacking the ability to 'group' items). I tried to mimic this functionality with various plugins in Obsidian in the past, but it didn't really work. I'll have to give it another look.

[BOOSTERHIDROGEN]

Check obsidian canvas.

[contingencies]

Markdown and git. Separate conceptual notes and requirements at a project level, generally allocate one repo per project or if complex, one repo per project module. Iterate on whole version numbers beneath that, ie.

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

[j45]

Obsidian or logseq.

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.

[jm4]

+1 for Logseq. I have tried so many note taking and organization apps. Logseq had a little bit of a learning curve, but it works better than anything else for my ADHD brain.

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.

[swah]

When it works, it works. But just having a dozen pages for each project and maybe a few fixed pages (say "Currently reading") also work. Not sure what is better.

[JohnFen]

I don't design hardware professionally, but I do a lot of it personally. I document these projects the same way I document my software projects: on a wiki I run on a home server.

I've tried many methods over the years, but in the end, the local Wiki serves my needs the best.

[bluemole88]

We use AllSpice.io. I'd look into it. You can talk with the person we use for support here: https://meetings.hubspot.com/marcus-marsall

[gtvwill]

Nothing. If the device isn't obvious in what's its used for maybe a quick sharpie note of button function but even that feels excessive. Most projects are sprawled out across some part of the shed. They might work they might not. It's a dice roll. Yolo.

The documentation is stored similarly in MD files splattered throughout a "notes" folder synced between my devices.

It's mostly unorganized chaos.

[brunohaid]

Solidworks and Altium (mostly Git based by now) output, as well as Google Docs / Sheets documentation, which then all gets pulled into prettified Indesign pdf Books automatically for users / rest of the team.

http://emsoftware.com/products/docsflow/ for GSuite to Indesign.

[ericfrazier]

Through business losses on my yearly taxes

[pedalpete]

We're in hardware and health-tech, so we require an QMS system, but we're also a team of former software engineers, so we're starting off by using Git.

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.

[mcsniff]

The same as all my other projects -- in a named directory with plain text notes, drawings, and anything else to support the project, all checked in and versioned with git.

Granted, these are "personal" (still revenue generating) projects and the bus factor is 1, but it works for me.

[tra3]

What's the best way to label wiring?

I used my sweet label maker till I realized that it prints on heat sensitive paper and the label eventually fade out.

[proxysna]

Trillium notes. Works pretty well for my homelab. Keeping inventory of all the things i have, how they are set up and relations between them.

[2bluesc]

Self hosted Gitea + Markdown + Mermaid diagrams

[jopizio]

I'm curious to know how you're using Mermaid diagrams for hardware. Can you give an example?

[2bluesc]

I typically (mis)use class diagrams as block diagrams for system design and interconnects.

[ukuina]

Google Doc, though performance suffers for image-heavy or long docs. Wish they would include support for Ink.

[bgnn]

Perforce is the standard in IC design and verification.

[iancmceachern]

Confluence, slack and shared folders

[exe34]

Emacs/org-roam.