The agency call always begins the same way. “The site is slow, the checkout page confuses people, and nobody remembers why we built it like this.” Somebody left, somebody else inherited the project, and the reasons behind a hundred small choices went with the first person out the door. That is the problem a website decision journal solves, and the diagnosis below follows one imaginary small-business site from symptom to fix.
The symptom: a site nobody dares to touch
Picture a regional training company whose website runs on a popular content management system. Over three years it picked up a page-builder plugin, two form tools, a caching layer and a theme with a dozen custom templates. Each was added for a reason. None of those reasons is written anywhere.
Now the owner wants a faster homepage. The developer asked to remove the page-builder, but nobody knows whether anything depends on it. Everyone is afraid to click delete. The site has become a museum of past decisions with the labels missing.
The diagnosis: decisions without memory
Look closely and the issue is not the technology. Plugins, themes and templates are ordinary. The trouble is that each was chosen under particular conditions, such as a deadline, a budget limit, or a feature a client had just asked for, and those conditions evaporated. Without them, a future maintainer cannot tell whether a choice was clever, lazy or temporary.
This is the classic pattern in web projects. The code survives, the thinking does not. A decision journal is how you keep the thinking.
The fix, part one: start a short decision log
For a web project, the log can be a single page in the project folder or a plain text file in the repository. Each entry holds five lines.
- What was decided, in one sentence.
- What else was considered.
- Why this option won, including any constraint such as budget, deadline or hosting limits.
- What you expect to happen: faster pages, fewer support emails, easier editing.
- When you will check, and how.
For our imaginary site, the first entry reads: “Chose a lightweight caching setup over a full performance suite. Constraint: shared hosting with limited memory. Expect page load to improve noticeably on the course pages. Check at the end of the month with a before-and-after test.” Short, honest, checkable.
The fix, part two: backfill carefully and label it
You cannot recover the past perfectly, but you can reconstruct the major choices. Ask the people who were there. Look at invoices, commit messages and old emails. Write each recovered entry with a note: “Reconstructed from memory; reasoning may be incomplete.” That label is important. It tells the next reader how much weight to give the entry, and it keeps new, properly recorded entries visibly distinct from guesses about the past.
The fix, part three: apply it to planning
A log is most useful before a build begins. When planning a new section or a rebuild, the choices about structure, page count and navigation benefit from being written as predictions. Advice on getting a business site mapped out ahead of the build lay out the questions to ask up front; the journal is where your answers and your reasons live afterwards.
The same goes for content decisions. If you choose to keep a trust-building page near the top of the menu, perhaps following advice about why an About Us page matters for credibility, note what you expect it to do: more enquiries, longer visits, fewer “who are you?” emails. Then you can test it.
What happened to the imaginary site
After the first month of logging, the owner reviewed the entries. Three of five predictions held. The caching change helped the course pages but barely moved the homepage, which turned out to be slowed by the page-builder itself. That finding was not obvious before the journal existed, because the earlier belief had been “caching fixes everything.”
The team wrote a new entry: “Plan to replace the page-builder on the homepage with a simpler template. Alternative: leave it and live with the delay. Reason: the test shows the builder, not the hosting, is the main drag. Expect a clear speed gain and slightly more work when editing.” They tested a staging copy, found it fine, and moved forward without the old fear of deleting things blindly.
A sample entry for a technical choice
Engineers will recognise the shape of an architecture decision record, just trimmed down for a small team. Here is how one might look for a plugin question:
- Decision: Keep the form plugin we already have rather than switching to a newer one.
- Options weighed: Stay put; migrate to the newer plugin; build a custom form handler.
- Reasoning: Migration would take two days and risk losing past submissions. The current plugin meets every requirement we can name today.
- Expectation: No change in spam levels; no new maintenance burden over the next quarter.
- Trigger to revisit: A security notice, a feature we cannot live without, or an editing complaint from the content team.
The “trigger to revisit” line is a quiet gem. It records the conditions under which today’s sensible choice stops being sensible, so nobody has to rediscover them in an emergency.
The human side of the problem
Behind every untouchable site is a person who once made a reasonable call and moved on, and another who now carries the anxiety of maintaining it. A journal is a gift to that second person. It says: here is what we knew, here is what we hoped, here is where we might have been wrong. Reading it feels like receiving a letter from a colleague you never met, and it takes the sting out of inheriting someone else’s work.
Where a quick side trip fits in
Developers and marketers also research other sites for ideas. Say someone on the team studies how a vehicle rental and sharing marketplace, MotoShareGo, handles signing in through a central account, as a reference for their own login flow. The useful journal entry is not about the vehicles. It is about what the team took from the example and what they decided to do differently, so the idea has a documented origin.
Warning signs your site needs a journal
- Nobody can explain why a plugin is installed.
- New starters ask the same “why is it like this?” questions every time.
- Fixes get reverted because someone did not know they were deliberate.
- Performance work stalls because every change feels risky.
- Discussions loop around the same debates every quarter.
If two or more apply, the cost of not writing things down is already showing.
Keeping the habit alive in a busy team
Attach the entry to the pull request or change ticket. If a change is worth merging, it is worth five lines of reasoning. Add a recurring calendar item for review, monthly for small sites, quarterly for larger ones. When a prediction fails, treat it as a finding in a diagnosis rather than a mistake to hide. A site is a living thing, and a habit of honest records is what lets you trace a symptom back to its cause.
The quickest way to begin is to pick the last choice you made on your own site, write the five lines now while you remember, and set a date to check. The next time someone says “why is it built like this?”, you will have an answer, and it will be yours.