Live data from Hacker News

Ask HN: How do you document your hardware projects?

news.ycombinator.com

21–30 of 42 posts

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

#21
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

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

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

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

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

#24
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

CSG is not as useful as BReps

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

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

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

#26
post #25

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

Check obsidian canvas.

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

#27
post #25

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

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.

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

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

/README.md defines problem, requirements, interfaces and any notes on structure and approach investigated or selected.

//v7/ alternatively /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.

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

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

Post reply on HN