The weekend I got organised and lost a port number
I once spent most of a rainy weekend building a personal work wiki. A database of clients, a page per project, properties for status and priority, a tidy template for meeting notes with a little icon on each one. By Sunday evening it looked wonderful, and I had the specific glow of someone who has finally got organised.
About five weeks later a small business site I had built stopped sending contact form emails after the owner changed hosting plans. I needed the mail settings their host wanted. I found them in three places. My wiki said port 587. The ticket from the original build said 465. A chat thread with the client said "use whatever the host recommends", followed by a screenshot I could no longer open.
The wiki was the fastest to search, so I trusted it first. It was the stale one. I had copied the value in during that weekend and never touched it again, while the ticket had been corrected a month after launch, when the first setting had failed. Twenty minutes of a client's site being broken, partly because I had built a beautiful second copy of the truth.
That is most of what I know about work notes, in one port number. The rest of this is how I keep notes now, which is smaller and much less pretty.
Why second Notions fail
Your work already has places where the truth lives: tickets, pull requests, project docs, the client folder. A personal wiki built alongside them starts as a good idea and turns into a shelf of outlines nobody opens, including the person who wrote them. I don't think the cause is laziness. It is structural, and it fails in three predictable ways.
It competes with the real home. You paste a paragraph into your private notes "for later". The ticket stops being updated, because you already wrote it down somewhere. Now two versions exist, and the stale one is the one you can find fastest.
It creates a retrieval question that did not exist before. Was the billing decision in the ticket, the meeting note, the wiki, or a chat thread? Every extra home multiplies that question. A note system earns its place by reducing the number of places worth searching, not by adding attractive ones.
It eats the best hour of the day. Designing databases, properties and tags feels like progress and produces nothing anyone else can use. Setup work is the most convincing form of avoidance available to people who enjoy organising things, and I say that as one of those people.
A note system earns its place by reducing the number of places worth searching, not by adding attractive ones.
A blunt test I now apply: if a note is not attached to a ticket, doc or pull request I will open again this week, it is clutter.
Three homes, and nothing else
Scratchpad, for today only
Links, half sentences, commands you ran, the staging URL, a permalink you will need in an hour. One place, either a single daily note or the bottom of your shutdown note. It is throwaway by design and gets cleared weekly. Nothing in the scratchpad is allowed to be the only copy of anything important.
Decisions, next to the project
Only the ones that would be expensive to rediscover. "Monthly billing only for launch." "API v1 stays until September." "Refund copy approved as written."
These go where the work is: a Decisions heading in the project doc, a line in the architecture record, a comment on the issue. That beats a personal knowledge base every time, because the next person to need the decision will not have access to yours. Often the next person is a colleague. Sometimes it is a developer the client hires after you.
Next actions, always
One clear next action per active thread, written where you will see it when you sit down. This is the layer that makes the other two optional, and why remote workers need a clear next action explains why it carries so much weight.
The filing rule underneath all three is proximity. Put the note where the work it affects already lives:
A decision about code goes in the issue, the pull request, or the architecture record
A client approval goes in the shared folder or the project thread
A meeting action goes in the task system with an owner and a date
A temporary URL or command stays in the scratchpad for the day and dies there
Link rather than copy when another system owns the truth, and add one sentence saying why the link matters. Refund copy approved by the client: [proposal section 4] is more useful than four pasted paragraphs that will quietly go out of date while still looking authoritative. If I had linked to the ticket instead of copying the port number, my wiki would have been right.
Capture fast, file on the break
Capture during a focus block follows different rules. Mid-block, the goal is speed: one scratch line with the next physical step, then straight back to the work. Do not open the project doc to find the right heading while you are holding a bug in your head. Filing happens on the break, when deciding where something belongs costs nothing.
A note that helps Monday you
Here is the kind of note I used to leave on a Friday: "fix tests later". On Monday I would spend forty minutes working out which tests, on which branch, and why I had thought they were broken.
The park note I leave now goes in the ticket, not a notebook:
"Branch feat/tax-line, failing CheckoutTest::eur_vat, suspect rounding in TaxCalculator.php line 112, next: dump $order->lines before the tax is applied."
That note lives where the work lives. Anyone who opens the ticket gets it, including a colleague covering for me. A copy in my personal notes would add nothing except a second place to forget to update. Restarting code where you left off goes further into the park note itself. The useful question before you stop is what a stranger would need: where the work is, how to check it, and what not to redo. That is the same bar as leaving work someone else can continue.
Chat is not a note system
Threads scroll away. Decisions buried in chat become folklore, and folklore drifts. When a thread resolves something, paste the conclusion into the ticket or doc in three lines: who decided, which option, what changes on Monday.
Meetings work the same way. If a call settles a question, three lines in the ticket beat five pages in a private doc. Attendees forget. Search does not, as long as the conclusion lives somewhere searchable. Documenting team decisions without bureaucracy is the team habit. Everything here is the solo version.
Search beats taxonomy
Personal wikis tempt you into elaborate tag systems. I had seven properties on my project pages and used two. Tickets and repos already have search. A decision in an issue title or the first comment is findable by anyone. A decision on page seventeen of your notebook is findable by you, on a good day.
The cheap trick is to put decisions where search will hit them. Title the ticket "Decision: monthly billing only at launch" instead of adding a property called BillingPhase to a database only you can see.
One note file per client, kept with the client
When I am juggling several client codebases, the temptation is a central workspace that covers all of them. In practice it becomes a fourth job: tagging, syncing, searching across databases, remembering which view filters what.
What works better for me is one plain note file per client, kept in the repo or the client folder. Environment quirks, deploy commands, who approves what, the current staging URL, and that mail port. Open the repo, open the note. There is nothing to search across, because I am only ever working in one client's world at a time, and switching clients is hard enough without a shared notebook dragging the others along. Running a multi-client week without context thrash covers the rest of that problem.
When the engagement ends, the folder gets archived and the note travels with the work history. It does not linger forever in a personal wiki, looking current.
Ten minutes a week, and no longer
Once a week I read the scratchpad from top to bottom. Every surviving line gets exactly one of four outcomes:
Delete it, because the work is done
Move it to the project's durable home, if it turned out to be a real decision
Turn it into a clear next action, if it is an unfinished thought
Keep it one more week, with a reason written next to it
Ten minutes is the limit, and it is a diagnostic as much as a deadline. If the review needs an afternoon, the fix is capturing less, not reviewing harder. Don't spend it making headings prettier either. The goal is removing ambiguity before Monday.
Phone notes go through the same pass. A voice memo or a one-line note to self is fine at scratchpad level, but it has to land in the weekly review and either get promoted to a ticket or deleted. Unprocessed phone notes turn into a vague worry, which is not the same as remembering something.
Look hard at copied status information during the review. If a ticket has moved on, update the ticket and delete your copy. Private notes should never quietly outrank the place your colleagues actually read. That same habit makes the end of the day shorter, because the end-of-day status update becomes a summary of notes that already live in the right places.
Notes are not a vault
Work notes get shared on screen, pasted into the wrong window and forwarded by accident. Credentials, personal data and unsigned contract terms belong in the systems built to hold them. My own rule is short: if I would not paste it into the client folder, it does not go into my personal notes either.
When to refuse a new tool
New note tools are easy to justify and hard to abandon. Before adopting one, I make myself name the retrieval problem it solves. Real ones exist: onboarding new people, passing an audit, maintaining a service for years, coordinating decisions across teams that do not talk daily.
If the honest answer is closer to "it would be nice to have everything in one place", I refuse it. That is a feeling, not a requirement, and no tool resolves it. The weekend wiki was exactly that feeling, with icons.
When a team genuinely needs a hub, keep it small. A handful of pages, a named owner for each, a review date, and links out to tickets for the detail. The hub points to the truth. It does not hold a second copy of it. Documentation without owners or review dates is a graveyard with better typography.
The working version of all this is less impressive than the wiki I built. A scratchpad you delete, decisions filed where the project can see them, one note file per client, and one next action per thread. That is a complete note system. Anything beyond it is a product you have volunteered to maintain, and I would rather spend that weekend outside.
End of this piece
Writer
PrimedEcho
Independent notes on remote work, focus, and freelance practice. About this site.
