Ask HN: How do you document your hardware projects? • Hacker News Board

jopizio wrote: post #12

2bluesc wrote: post #10

Self hosted Gitea + Markdown + Mermaid diagrams

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

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

Re: Ask HN: How do you document your hardware projects?

#14

Post by brunohaid » Thu, Jan 11, 2024, 5:19 PM UTC

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.

Re: Ask HN: How do you document your hardware projects?

#15

Post by letitbeirie » Thu, Jan 11, 2024, 5:22 PM UTC

em0sh wrote: post #7

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 draw…

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

Re: Ask HN: How do you document your hardware projects?

#16

Post by nine_k » Thu, Jan 11, 2024, 5:26 PM UTC

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.

Re: Ask HN: How do you document your hardware projects?

#17

Post by BillyTheMage » Thu, Jan 11, 2024, 5:42 PM UTC

nine_k wrote: post #16

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 cha…

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

Re: Ask HN: How do you document your hardware projects?

#18

Post by iancmceachern » Thu, Jan 11, 2024, 5:42 PM UTC

Confluence, slack and shared folders

Re: Ask HN: How do you document your hardware projects?

#19

Post by iancmceachern » Thu, Jan 11, 2024, 5:42 PM UTC

em0sh wrote: post #7

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 draw…

Do you use a PDM system?

Re: Ask HN: How do you document your hardware projects?

#20

Post by nine_k » Thu, Jan 11, 2024, 6:03 PM UTC

BillyTheMage wrote: post #17

nine_k wrote: post #16

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 cha…

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

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

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