Why I Started Keeping a Logbook for My Web Projects
I've been building websites for clients and myself since the table-layout days, and somewhere around 2016 I realized I was making the same mistakes on every third project. Bad session timeout handling. CSS specificity wars that took three hours to untangle. A JavaScript build step that broke because a dependency shifted. I'd move to the next job, sweat through it, then do it all over again a month later on something completely different. The logbook is just a local markdown file, structured in a way that actually survives contact with reality. Not a diary. Not a blog. A searchable, timestamped record of what I tried, what worked, what broke, and why.
Diy Web Development Logbook
The core idea is simple: you create a single file—usually called dev-log.md or something similar—and you append entries as you work. Each entry gets a date, a one-line summary, the problem, the fix, and a tag or two. That's it. No framework required. No database. Just a text file that grows with you. Here's the structure I use, which you can copy directly:
2024-11-03 — Session timeout on staging API
Problem: Client-side SPA kept redirecting to login at random intervals, even though the token was valid.
Investigation: The JWT refresh endpoint was returning 401 because the staging nginx config had `proxy_read_timeout 30s;` and the auth service occasionally needed 45-60s to respond under load.
Fix: Bumped `proxy_read_timeout` to 120s in nginx, added a retry with exponential backoff on the frontend using axios interceptors.
Tags: #nginx #jwt #staging #api-timeout
This format forces you to be specific. You can't write vague notes like "fixed the login thing" and expect to find it useful six months later when the same problem reappears. The tags are critical. After about two dozen entries, I have a working index of every category of failure my projects encounter. I keep the logbook in the root of each project's repository, but I also maintain a separate master log at ~/logs/dev-log.md that aggregates cross-project observations. That's where I catch patterns—like the time I noticed I'd logged the same CORS misconfiguration workaround four times across three unrelated client projects in six months. One practical thing people get wrong about this: the logbook should be written in real time, not retrospective. I used to try to fill it in at the end of the day. It never happened. The details fade within hours. I started writing entries inline, saving them as part of the commit habit—write the note, stage it, commit both. Takes maybe 20 extra seconds per entry.
Get the Full Details
What It Actually Looks Like After a Year of Use
After a year, the file gets long. Ours runs about 14,000 lines. Searching it with grep -i "cors" or rg "nginx timeout" from the command line is where the value really shows up. You'll find solutions you already wrote, tested, and validated. That's better than reinventing anything. Here's a specific edge case I ran into that the logbook saved me on recently. I was working on a Next.js project that needed to pull data from a WordPress REST API. Everything was fine locally, but in production the API would intermittently return malformed JSON—truncated responses, about 1 in 50 requests. Took me three days to reproduce. I checked headers, timeouts, buffer sizes. Nothing. I found my own entry from eight months prior in the logbook, tagged #wordpress-rest #truncated-response. On that older project, the same issue existed because the WordPress server was behind a Cloudflare proxy with "Always Online" mode enabled, and the cache was serving a stale partially-loaded page on the REST endpoint. The fix was adding a specific cache-busting header to the API requests and disabling "Always Online" for the WordPress subdomain. Copied the same approach, worked immediately.
That entry had been written by a version of me who was just as frustrated as I was, except this time I didn't have to be.
Counter-Intuitive Things You'll Probably Get Wrong
The first mistake people make is treating the logbook as a todo list or a changelog. It isn't. A changelog records what shipped. A todo list records what needs doing. The logbook records what happened and what you learned. Those are different things. When I tried combining them, the file became noise within a week. I separated them: changelog goes in CHANGELOG.md, tasks go in the issue tracker, the logbook stays strictly for post-mortem style entries with a problem, investigation, and resolution. The second mistake is making it too formal. I once spent twenty minutes formatting an entry with perfect prose and nice categories. Didn't touch it again. The entries that survive are the ones written fast, with raw commands and broken error messages included verbatim. Copy-paste the terminal output. Paste the network tab response. Don't sanitize it into readability. Future-you needs the exact error string to grep against. There's also a limitation worth acknowledging: this system doesn't scale well past about three concurrent projects. Once you're managing six or seven active repos, the per-project logbooks multiply, and the cross-references get messy. In that situation, I switched to a single SQLite database with a simple schema—date, project, tags, problem, fix, source_link—and query it with sqlite3 or a small CLI wrapper. The principle is identical. Only the storage changed.
How to Set This Up Today
You don't need to download anything. The Diy Web Development Logbook is, at its simplest, a file and a habit. But if you want a starting template that's been through enough projects to be useful, here's the minimal setup: I keep a shell alias in my dotfiles: logentry() { echo "$(date +%Y-%m-%d) — $1" >> ~/logs/master-dev-log.md; } . I type that when I hit a meaningful problem, add the title, then edit the file manually to fill in the details. It removes the friction of deciding whether now is a good time to start writing. The only resource I'd point you toward is the actual logbook file format itself—there's no official standard, which is the point. The one I maintain is available at a few mirrors online, but honestly, the template above is sufficient. What matters is the discipline of recording, not the tooling around it.
