6 ms·

Ask HN: How do you document your hardware projects?

• RB333 3y ago
  Git commits for hw - https://allspice.io/post/git-for-hardware-commit-best-practices https://allspice.io/post/git-for-hardware-commit-best-practi...
• iancmceachern 3y ago
  Confluence, slack and shared folders
• j45 3y ago
  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 3y ago
    +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 3y ago
      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.
• wibbily 3y ago
  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 3y ago
    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.
• Pulz 3y ago
  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.
• proxysna 3y ago
  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.
• em0sh 3y ago
  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 3y ago
    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 3y ago
    Do you use a PDM system?
    • em0sh 3y ago
      At work. I think it’s not very good most of the time.
      • iancmceachern 3y ago
        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.
• ericfrazier 3y ago
  Through business losses on my yearly taxes
• ukuina 3y ago
  Google Doc, though performance suffers for image-heavy or long docs. Wish they would include support for Ink.
• 2bluesc 3y ago
  Self hosted Gitea + Markdown + Mermaid diagrams
  • jopizio 3y ago
    I'm curious to know how you're using Mermaid diagrams for hardware. Can you give an example?
    • 2bluesc 3y ago
      I typically (mis)use class diagrams as block diagrams for system design and interconnects.
• brunohaid 3y ago
  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/ http://emsoftware.com/products/docsflow/ for GSuite to Indesign.
• nine_k 3y ago
  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.
  • BillyTheMage 3y ago
    I think version control like this would work great with programmatic CAD like OpenSCAD
    • lincoln20xx 3y ago
      Git works great with text-based code-cad. My personal favourite flavor is build123d, which is based on cadquery.
    • nine_k 3y ago
      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 3y ago
        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 https://www.perforce.com/products/versic
• JohnFen 3y ago
  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.
• exe34 3y ago
  Emacs/org-roam.
• zeagle 3y ago
  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.
  • BOOSTERHIDROGEN 3y ago
    Check obsidian canvas.
  • jopizio 3y ago
    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.
• contingencies 3y ago
  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.
• bgnn 3y ago
  Perforce is the standard in IC design and verification.
• mcsniff 3y ago
  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.
• pedalpete 3y ago
  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.
• tra3 3y ago
  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.
• gtvwill 3y ago
  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.
• bluemole88 3y ago
  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 https://meetings.hubspot.com/marcus-marsall