How to Journal

Why Journal?

When you finish a project, it's easy to forget how much work was put into it. There may be times where you spent five hours on a module that you decided to scrap anyway, or where you completely revamped your project. Iterations always exist in hardware projects! When you look back at the project a few years from now it'll be very difficult to remember anything about it. Your journal is where all of that lives!

Additionally, without a journal, your steps are not documented. It's impossible for people to learn from a project merely from the final product. Your journal allows other people to understand your research, the effort put into the project, and all the steps taken to reach the final product.

In this program, your journal is also how reviewers verify your work. They're reading it to understand what you built, confirm the hours you're claiming, and see that you actually understood the decisions you were making, not just that you followed a tutorial or copied a reference design.

Where Does It Live?

Your journal goes in a file called JOURNAL.md in the root of your GitHub repository. Every session of work gets its own entry, added to the bottom of the file. Not sure how to format it? Check out this Markdown formatting guide.

How Do You Journal?

A good journal reads like a story. Not a dry log of actions, but a real account of your build: what you were trying to do, what happened, what went wrong, and how you got through it.

Every entry covers one session of work. It should, in general, include:

• What you did
• Why you did what you did
• What issues you ran into

Explain your decisions, not just your actions!

The most important thing you can do in a journal entry is explain why, not just what.

Bad:“I added a buck converter.”

Good:“It might be a bit wrong, but I'll figure that out in a bit, for now, we need to convert the 12/24V down to 3.3V for the MCU. It's a bit complicated to wire, but basically just steps down to 3V3, and then stabilizes and protects it using some capacitors and diodes, and then it needs some internal voltage too, which is what the FB pin is for. And just like that, we have a buck converter for the PSU! But I still kind of need to convert the 5V from the USB down to 3.3V for the MCU, so I might need to re-use the current buck converter if I can, or add another one... But anyways, after reaching out to some people, they suggest I use a different buck converter because of the bad switching frequency, and also convert to 5V instead of 3.3V and then use an LDO to get from a 5V rail to 3.3V. So after a bit of research, I'm just going to use the TPS54331 chip. So after an absurdly long time, I got the buck converter wired for 12/24V to 5V.”

Found in Kai's journal here! I heavily encourage reading it, it's a nice read :D

Reasoning is very important! Anyone can describe what you did, but explaining why proves you understood it.

Screenshot everything!

Take screenshots of your work at every meaningful step, not just when it's done and clean.Show the messy intermediate states. Show it before and after you fix something. Kai's journal is a great example of this!

Describe your mistakes

Making mistakes is an integral part of any project. Real hardware work is full of things going wrong: footprints that were off, wiring that had to be redone, suggestions from reviewers that changed your approach entirely. These moments are some of the most valuable things to document, because they prove the work was real and they're often where the actual learning happened.

A journal with no mistakes reads as a summary, not a journal.