$100 Website Offer

Get your personal website + domain for just $100.

Limited Time Offer!

Claim Your Website Now

The Untouchable Website and the Decision Log That Fixes It

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.

  1. What was decided, in one sentence.
  2. What else was considered.
  3. Why this option won, including any constraint such as budget, deadline or hosting limits.
  4. What you expect to happen: faster pages, fewer support emails, easier editing.
  5. 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.

Related Posts

Near Misses as a Career Skill for Web Developers

Why handling a caught mistake well is a learnable skill for CMS and web developers, and how to show it in a portfolio or interview.

Read More

Five Website Clean-Up Myths That Keep Your CMS Cluttered

Five comfortable beliefs about website housekeeping, and the simpler habit that replaces them: trim drafts, plugins and media files as you work.

Read More

Website Teardown Checklist: Audit a Finished Business Site First

A practical five-part checklist for taking apart a finished business website, structure, content, navigation and technical clues, before you plan your own CMS build.

Read More

Eight Plain-Word Fixes for Clearer Website Copy and CMS Labels

Menus, buttons, error messages and admin fields often use insider words. Eight practical fixes, each with a before and after, to make your site easier to read.

Read More

Page Cap, Plugin Cap or Palette Cap: Which Site Limit Fits?

A friendly comparison of three self-imposed limits for CMS builds, covering pages, plugins and palettes, with when each one helps and where it hurts.

Read More

Why Web Projects Slip: Diagnosing the Unchosen Trade-Off

Late, over budget and still rough? A diagnosis-first look at web projects that never decided whether speed, cost or quality would give, plus the written fix.

Read More
Subscribe
Notify of
guest
0 Comments
Oldest
Newest Most Voted
0
Would love your thoughts, please comment.x
()
x