I've been building Jottings for the better part of a year now, and if there's one thing I've learned, it's that my git commit messages are terrible historians.
Don't get me wrong—I'm diligent about commits. They're frequent, they're descriptive, and they tell you what changed. But they rarely tell you why I made a decision, what problems I ran into, or how I felt about the direction the project was taking at 2 AM on a Tuesday.
That's what project logs are for.
The Gap Between Code and Decisions
A few months into building Jottings, I realized I was stuck in a loop. I'd implement a feature, commit it, and move on. Three weeks later, I'd come back to that same feature wondering: "Why did I structure it this way? Were there problems I was trying to solve?"
I could dig through git history, but commit messages don't capture context. They don't explain the dead ends I explored or the architectural decisions I abandoned. They don't record why I chose DynamoDB over a relational database, or the six hours I spent debugging why Lambda timeouts were killing my builds.
That's when I started keeping a project log.
What Goes Into a Project Log
Unlike commit messages, which are technical and concise, project logs are spacious. They're the thinking-out-loud version of your development work.
Here's what I include in mine:
The problem I'm solving: Not the immediate coding task, but the actual user need or technical debt it addresses. This sounds obvious, but it's rarely captured anywhere else.
The approach I chose: Why this solution over alternatives? What tradeoffs did I make? This is gold when you come back to the code six months later.
Blockers and breakthroughs: The frustrating bugs that took me down rabbit holes. The sudden insights that made everything click. These aren't valuable for anyone else's immediate debugging, but they're valuable for your own learning pattern.
Decisions about the codebase: New patterns I'm introducing, libraries I'm adding, architectural changes. These are the things that shape how future work will feel.
How I'm feeling about it: This sounds sentimental for a dev log, but it matters. "This was the hardest part so far" or "This felt surprisingly elegant" helps you remember not just what you did, but what was difficult and what worked well.
Here's a real example from my logs:
"Finally migrated to atomic DynamoDB transactions for site creation. The race condition where totalSites wouldn't increment was driving me crazy. Spent two hours trying to fix it at the API level before realizing the problem was architectural. Moving counter updates into the same transaction eliminated the issue completely. This is probably the best architectural decision I've made so far—everything feels less fragile now."
That entry is 40 words. My commit was one line: "feat: use DynamoDB transactions for atomic site creation."
Tags: Organizing Across Projects
If you're like me, you juggle multiple projects. Work stuff, side projects, personal experiments. A project log isn't useful if you can't find the entry you need six months later.
I tag everything. #jottings-core for backend work, #jottings-frontend for dashboard changes, #infra for deployment and architecture, #bug for debugging sessions. When I want to remember how I handled image uploads, I search for #media-uploads. When I'm wondering about past Cognito integration decisions, I find #auth.
The nice thing about tags is they're flexible. They're not a strict taxonomy—they evolve with your work. If you suddenly start doing a lot of database optimization, you might create #performance. If you're refactoring a subsystem, #refactor works perfectly.
Public or Private?
Here's a question that comes up: should your project logs be public?
For Jottings, I keep mine private. I want to be honest about my frustrations, about mistakes I made, about times when I was completely stuck. That honesty is easier without an audience.
But I've seen developers who do the opposite—they keep public development logs as a way to build an audience, document their learning in real-time, or create a transparent record of how they built something. Both approaches are valid.
The magic isn't in who reads it. The magic is in the act of writing it down.
Why This Actually Matters
You might be thinking: "This sounds nice, but is it really necessary?" Maybe you've got good memory. Maybe you take notes in Slack or GitHub issues. Maybe you just move forward without looking back.
I get it. But here's what I've gained from keeping project logs:
Solving the same problem twice: Last month I needed to implement pagination. I searched my logs, found an entry about it from two months ago, and remembered not just how I did it, but why I structured it that way. Saved me an hour of thinking.
Understanding my own patterns: After months of logging, I can see that I consistently underestimate how long refactoring takes. Or that I solve problems better when I step away and come back. Self-knowledge that's hard to acquire any other way.
Teaching future me: My codebase will eventually be maintained by someone else. My project logs won't be included in the repo, but they're immensely valuable for onboarding. "Here's why this is structured this way, and here are the constraints that made us choose this approach."
Building confidence: On hard days, I can read back through entries and see real progress. "I thought the custom domain implementation would take three weeks—I did it in five days." These notes become proof that you're getting better.
Getting Started
If you want to start keeping project logs, you don't need a special tool. You could use a notebook, a notes app, anything. But I built Jottings specifically because I wanted a place that was quick to write to but easy to search and organize later.
The workflow is simple:
- Open Jottings when you finish a significant piece of work
- Write what happened—the problem, the solution, what you learned
- Tag it with your project
- Move on
You can add links to commits, PRs, or documentation. You can include code snippets. You can look back through your tag history and see exactly how your thinking evolved.
What I've discovered is that the act of writing slows you down just enough to actually think. It forces you to articulate decisions that usually happen in your subconscious. And it creates a record that becomes increasingly valuable the longer you keep it.
Your code is the artifact. Your project logs are the story of how you built it—and why. Both matter.
If you're interested in keeping your own project logs, that's exactly what Jottings is designed for. Simple, fast, and yours to keep however you want.