I’ve talked about a low-effort way to document your projects by taking plenty of pictures, and about ways that your PCBs could be documenting themselves. Today, let’s talk about a quick and easy way that you could help other hackers as you go through your own hacking adventures — leaving breadcrumbs.
In short, breadcrumbs are little pieces of crucial information that you had to spend time to figure out. They are solutions to problems that another hacker just like you could stumble upon in the future, something that you perhaps wish you didn’t have to figure out on your own, and certainly something that others won’t need to spend time figuring out.
Breadcrumbs are about saving time, for you and others. It helps if you think of your solved problems in terms of time spent. If you figure out a small problem and then publish your solution, you might be saving half an hour, a full hour, or a good few hours of time another hacker that’s could even be less experienced in debugging than you. In fact, your breadcrumb might even make a difference between someone completing a project and abandoning it!
However, there’s also the trade-off of taking time to document something. If you can’t publish your solution in a few minutes’ time, it might become much harder to persuade your brain to publish the next time you have something notable. Here’s a guideline: if you’ve just figured out a cool terminal command that helps you solve a certain kind of problem, you should have a quick way to publish that command within a minute. The good news is, the internet has a hundred different places you could easily share your findings, depending on the kind of problem you’ve solved!
Self-Publishing For Hackers
It’s exceptionally important that you minimize the time it takes to get something published. Don’t think that you need to start a whole fancy blog right now to publish that one note, it’s enough to create a wordpress.com account, or a new GitHub repository. GitHub specifically has the Gist platform that’s good for short notes, but you can also create a repository called ‘notes’ that contains a bunch of Markdown files with descriptive filenames. In fact, having a GitHub repository with markdown files is quite close to having a decent blog, with way less setup effort to boot. Check out this repository for a great example!
You don’t need a comment section plugin, you don’t need analytics, or fancy plugins, you don’t even need your own hosting, you only need a space for text and a bit of searchability. All you actually need is a place to post things quickly. You wouldn’t want to make your breadcrumbs hard to leave of all things, they should take as little time as possible. Having your favorite text editor open and at the ready certainly helps, so you can be 5 – 10 seconds away from copy-pasting your notes into a publishable document. A GitHub repo fits that bill, so does a WordPress blog, or even a Hackaday.io stack page.
When you’re choosing the text to put in your post it’s worth considering a bit of search engine optimization (SEO), which in our case boils down to, “what could another hacker be searching while trying to solve this problem?” So, weave in all the specific and general keywords and strings that you yourself have looked up in the search engine, get the specific error message name in there if you still have it, and, if your blog supports tags, add any tags that feel like they apply well. You’ll want to make it so that others can find this post when they need your help specifically!
Don’t expect comments or likes, or any feedback outside of a view counter. My WordPress stats page doesn’t show many views on my breadcrumbs, half of them are in 50 – 100 lifetime view range, and 40% are in the 100 – 1000 view range. However, even if 99% of these views are bots, that’s still a decent amount of people solving a similar problem overall. If you manage to help someone save one or two hours of debugging work, that’s a big win.
Having your own blog with breadcrumbs can certainly help you build up your own reputation, and it also has quite a bit of sentimental value. For instance, I feel good when I scroll through my old breadcrumbs blog nowadays; it has solution after solution, with each post likely having helped someone else along the way, and each post brings me back to some project I was working on. Maybe I was just hacking on something interesting in my free time, or maybe I was helping a friend, but either way it’s a nice reminder of the “oh, I was solving this problem once!” kind.
Still, with your own blog, there are disadvantages. For instance, unlike forum pages, you no longer have the SEO advantage of other people having clicked the search result before. What if you want to maximize the chance that the answer is found? What if you don’t have a blog yet and you just can’t get through the perfectionism barrier?
Get To The Source
We all know the tale — you find a forum thread where someone has the exact some problem as you, and the last message is “I solved it myself”, no solution in sight. It is frustrating to see, and if you’re looking for a bit of comfort, leaving breadcrumbs helps you move the world into the opposite direction.
Among thousands of dead platforms, you will absolutely see StackOverflow willing to help you with no strings attached, Reddit with its community recently torn apart, Blogger about to lose its entire picture collection, and the few forums left up and running. Still, all of these platforms have their spots in search engines, even if the first pages have been surrendered to AI-generated spam. Sometimes, accounts and threads will get deleted, hotlinked pictures will disappear, old posts might get locked, a plague on forums and Reddit alike if you just want to leave a breadcrumb. However, you’ll find yourself on their pages, still, and others will too.
As you were solving your problem, you have likely googled it in a few different ways. You might have a few kinds of browser tabs: GitHub issues, StackOverflow pages, forum threads, others’ blog posts, maybe even a public discussion that you yourself have started in the meantime. All of these are great places to post an answer — as long as it’s a page you have found through a search engine, the same search engine is more likely to lead people to the one crucial piece of information that you’ve found.
Websites like StackOverflow also recognize the concept of breadcrumbs. You can ask a question there, but you can also ask your own question and then answer it, and you can even ask a question specifically for the purpose of giving your own answer under it! Remember, StackOverflow has an electronics section! You’ve probably already stumbled upon it, but if you haven’t, here it is.
StackOverflow and Reddit do share a problem: they have minimum requirements for their posts, and you might not necessarily meet them. If your problem happens to fall under some sort of tragedy of commons guideline, or your question is perceived as too similar to someone despite vital nuance, it might get closed and downranked. Having said all that, my few StackOverflow answers have certainly helped others over time. I’ve once solved a small problem back in 2018, posted it as an answer, and to this day I still get upvote notifications for the solution I posted. Can’t deny, that alone warms my heart!
Publish Or Perish
It might not matter where you leave breadcrumbs as much as it matters that you do leave them somewhere. Most of all, it should be easy for you to leave them. Searchability helps, and if you can optimize for that, do so. Perhaps don’t leave your breadcrumbs on X (formerly Twitter), or any place you don’t often see in search results. Unless it’s your blog, in which case, you’ll surely soon make it to Google!
Even a tiny breadcrumb can point a fellow hacker in the right direction – and don’t you wish that you yourself had one handy before you embarked on a three-hour debugging journey?
One of my favourite breadcrumbs is writing directly on my point to point wired prototype boards, long before I commit to actual pcb, I have a board with plenty of small notes. Hint: Fine india ink pen.
This is also true for software projects. Put in comments–lots of them! And write documentation for the code. This is especially important for open source projects so that others can contribute without having to spend hours reverse engineering the code.
There’s a better solution to putting Markdown files inside a GitHub repository: GitHub pages.
It even works perfectly well with Docsify and it possible to generate sites using Jekyll.
I host my own blog on GitHub as well.
I just did something like this for the BeaglePlay. I wanted to use the CAN interface on the mikrobus connector but there were no examples on how to do it. So after some trial and error and many many google searches and reading TI’s PDFs I pulled it off. Then immediately documented it on their forums, if for anything for me to read again once I forget in a week.
While I do have a blog it’s been embarrassingly long since I’ve updated it. Instead I’ve switched to youtube.
I’ve made a few videos on stm32 configuring along with touchscreens and the videos was primarily meant for myself so I could figure it out later on.
Turns out that quite a lot of people was looking for this particular bit of knowledge so I ended up with 25k views on one of the videos! Funny how that worked out
In the spirit of this article, and having nowhere better to share it.
I think the best advice I could give to anyone taking a new or unknown piece of kit apart is, if you can muster the space to do it. Start with the hardware to be dissmantled/fixed at one end of a clear bench. Every time you remove a piece leave it and it’s fastners arranged there and move down the bench. To reassemble just head back up the bench piece by piece. Pictures and documenting are important tools, but good physical organisation can make life so much easier.
That said, thanks to everyone who’s sharing has either answerd or led me to the answer online. I Hope the few breadcrumbs I’ve left have helped someone however unlikley.
I do the same sort of thing. When disassembling an engine I put the bolts and components furthest away in my available space, Some patterns of bolts might have different lengths so they get pushed through a sheet of cardboard in an arrangement matching their position.
Marking bearing slippers, rods etc get light centrepunch marks, other things get Sharpie marked and so on.
cardboard or styrofoam egg cartons are good for organizing pushrods and bolts that need to go back where they came from. You can punch the pushrods through the top. And they’ll handle everything up to a V12!
Great idea, thanks!
Had it to be GitHub?
Gah.
I get that leaving breadcrumbs is a good and altruistic thing to do for others. More importantly, though, it is good for YOURSELF. As a professional scientist the true value of a clear lab notebook was so *I* could go back later and figure out what I did without reinventing the wheel. Especially for stuff you figure “I would never forget that!” then, seriously 1 week later you can’t remember at all. There is a reason the first week of any real science class in high school or college is all about the lab notebook and keeping one poorly is graded harshly. Or at least it was, or maybe I was just lucky to have it beat into me early on.
My strategy is a bit different. In my projects various net searches, I often come upon husky yet incorrect responses to honest questions and so much gatekeeping ego that it makes me shake my head. When I retire in a couple of years, I plan on spending that golden two hours in the morning in between walkies and my own constitutionals to sit there with a cup of coffee and straighten out the internet lol. Go thru this bookmark folder of buttnuts and create accounts and respond properly on various forums so that people only have to look one place once and not have 8 tabs of competing levels of wrongness only revealed 20 pages into the post. Probably just dump my mobo pics too for the possible good of mankind as I do deal with odd gadgets of all eras and types. But yep, just gonna live the old man golden dream of telling people they are wrong on the internet lol. That and lots of fishing and perfecting my automatic duck feeder. The wife is doing something similar, but related to her field of interest.
Love it.
Leaving notes to yourself on component packaging / source code / tools etc. is good advice. And making your documentation public encourages you not to skip details that you (wrongly) assume you’ll remember next time.
But none of this really helps other people FIND your tips. For that, the only helpful suggestion above is to use Stack Exchange, and unfortunately, SE’s deep-seated cultural problems really don’t make it easy. Anything accessible and noob-friendly is likely to get “corrected” by one of the local know-it-alls to something they think sounds smarter, but is often less helpful and more obscure. Also, while they encourage to answer your own questions, the incentive structure penalises threads like that, making them less active and harder to find.
(If you can’t tell, I find SE’s design choices super frustrating)
I worry about online documentation become impossible to find in the future. Platforms come and go all the time. Best thing is a good schematic with notes and test points with expected values. Enclose or affix the schematic to the device if possible. I have been saved many times by tech data packages inside devices I have worked on.
If I’m making PCB’s for myself or prototypes I put as much labelling & description as possible on the silkscreen and notes in the schematic.
For all my personal stuff I run a Dokuwiki which can be locally self-hosted or put on an actual web server – it’s easy to install & maintain (& backup!), writing notes in a sensible format is easy and it’s easy to make a well organised structure.
For projects alone (my Dokuwiki is my all-purpose notebook) a locally hosted Gitea install works really well on any old hardware you have laying round.
I document on my blog, mostly for myself, but I’ve had a few comments of people who liked my posts so I think there must’ve been 10s of ppl who found it helpful.
I have a basic install guide for headless Raspberry Pi’s documented when I installed one and I use that everytime I install a Pi. (https://iivq.net/making-a-nas-out-of-my-raspberry-pi-4/)
It includes useful tidbits like
“disabled wifi by adding
dtoverlay=pi3-disable-wifi
to /boot/config.txt – the pi3 works for the Pi 4, and the claimed also-working disable-wifi does not work.”
Thanks for this. I just downloaded these from your blog. Great stuff.
I have had a GitHub account for a long time. I just discovered Gitea. I now have my own local Git repo thanks to Gitea and do everything there. If I want I can upload to GitHub but since Microsoft took it over I am a little leary of it.
Gitea is great. It supports all kinds of stuff, CI/CD, Organizations and more. I’m now a fan….
I was banned from the StackOverflow franchise for making a jokey slightly derogatory remark to one of their moderators. Probably related to CSH, I forget.
So now they deny the world my 30+ years of computing and electronics experience. Oh well.