What I actually use to track ML experiments without drowning in spreadsheets
Most people I see trying to build a Machine Learning Journal Minimalist end up creating something that looks nothing like what they wanted. They start with five fields and by the third experiment they have forty columns and nobody is updating it anymore. I learned this the hard way during a project where we trained roughly two hundred variants of a classification model over six months. The tracking sheet became so bloated that we stopped recording hyperparameters altogether, which meant when something worked we had no idea why. The approach I settled on strips everything down to the point where it actually gets used. It is not about elegance. It is about survival.
Setting up a Machine Learning Journal Minimalist
Start with a single CSV or JSONL file. No database. No Notion workspace. No fancy dashboard. Just rows you can grep through when you need to find a result from three weeks ago. Each row should have exactly these fields, nothing more: date — just the date, not the timestamp. You do not need the hour. dataset — the name of the data source. If you modified it, note that separately.
model_type — "xgboost", "svm", "transformer_finetune". Keep it short. key_hyperparams — one line, semicolon-separated. This is where most people fail because they try to capture everything. Capture only what changes between runs. If learning rate, batch size, and number of trees are the variables you are actually tuning, that is three items. Nothing else goes here. metric_name — the single metric you are optimizing. Pick one. If you have five competing metrics, you do not have a model, you have a committee.
Get the Full Details
metric_value — the number. notes — a free text field for things that do not fit anywhere else. That is it. Six columns. I have been using this structure for about two years across different teams and different types of problems. The simplicity is the whole point.
Why this actually works compared to the alternatives
There are tools like MLflow, Weights & Biases, and Kubeflow. They are fine if your organization has the engineering overhead to support them. Most people do not. A five-person team cannot maintain an MLOps pipeline the way a team of fifty can. The overhead of setting up tracking infrastructure often exceeds the time you would save by having good tracking. With a flat file you can work offline. You can version control it with git. You can query it with any language. When the tool breaks — and tools always break — you still have your data. That mattered to me when a cloud provider changed their API pricing and we had to shut down our experiment tracking service mid-quarter. Everything in the CSV was intact. Nothing in the dashboard was recoverable. The downside is that it does not scale to thousands of experiments. If you are running automated hyperparameter sweeps across hundreds of configurations, a spreadsheet becomes unreadable. In that case you need a proper database. But most real-world ML work does not hit that scale. It hits the scale where a file with two hundred rows is already painful to scroll through.
A concrete problem I ran into and how I fixed it
Here is the edge case that nearly broke my setup. We were doing time-series forecasting with multiple train/validation splits. The key variable was the date range of each split, and that field did not fit neatly into any of the six columns I had defined. My first instinct was to add a new column called "split_dates". Then another called "lookback_window". Then "forecast_horizon". Before I knew it I was back to thirty columns and nobody was filling them out consistently. The fix was to concatenate all the structural metadata into the notes field in a standardized format. Every entry started with the same prefix pattern: split=train_2023Q1_val_2023Q2; lookback=60; horizon=14; seed=42
I kept the format consistent enough that I could parse it with a simple script when I needed to filter. The trick was committing to the convention. If one person writes "fold=1" and another writes "split=A", the grep approach falls apart. I made it a rule: the notes field follows a strict key=value pattern separated by semicolons, and anything that does not fit that pattern does not belong in the journal. This saved us from creating yet another column and kept the core table at six fields. It felt restrictive at first but turned out to be the right constraint.
How to actually maintain discipline with this approach
The hardest part is not setting it up. It is remembering to write to it. I have seen too many people build a beautiful tracking system and then never use it because the friction of recording is too high. The simplest workaround is to make logging automatic. Write a small decorator or wrapper function that records each experiment before it starts and after it completes. In Python this looks like a context manager that opens the CSV, writes the row, and closes the file. You should not have to think about writing to the journal while you are training. The act of calling the function should be as lightweight as possible. If you are doing manual experiments where automation is not feasible, attach the logging step to something you already do. I tied mine to the git commit. Before pushing code, I run a one-line command that prompts me for today's results. The command is short enough that it does not feel like a chore. It takes about ten seconds.
Another thing that helps is reviewing the journal weekly. If you are not looking at your own records, they become fiction. I found that a fifteen-minute weekly scan of recent entries was enough to catch patterns. Missing that step is what causes journals to die. People stop trusting their own records because they stopped checking them.
When this approach will fail you
Be honest about the limitations. A minimal journal does not handle collaborative work well. If five people are running experiments on the same machine, you need locking logic or a shared storage layer. File conflicts will destroy your data. In that scenario, even a lightweight database like SQLite is worth the setup cost. It also does not store the actual model artifacts. You will need a separate system for saving checkpoints and weights. The journal should only track metadata, not binary files. I used to try to embed model paths in the notes field, which made everything messy. Keep the model files in a dated directory structure and reference the path in the notes. That is the cleanest separation. For visualization, you will need to build your own scripts. There is no built-in charting. I use a simple Python script with matplotlib that reads the CSV and plots metric values over time. It takes maybe an hour to write and a few minutes to run. Custom-built, but fast enough that I do not avoid it.
Practical setup instructions
If you want to start today, here is the exact process I would follow: Create a file called journal.jsonl in your project root. Each line is one experiment record in JSON format. JSON is preferable to CSV because you can nest simple structures if you ever need them, and most languages handle JSON natively without parsing quirks. Write a logging function in your project's utility module. It should accept the six fields, append a line to the file, and return nothing. Make it impossible to forget by importing it at the top of every training script.
Do not add a UI. Do not add authentication. Do not add search features. If you need search, write a one-off grep command. The moment you add a UI you are in software engineering territory, and that is where minimalism goes to die. I keep the journal at roughly two to three megabytes across dozens of projects. That is manageable. Anything larger and I switch to a different strategy. But the threshold is much higher than most people expect because the format is so compact.
Summary thoughts on the Machine Learning Journal Minimalist
The core insight is that tracking systems die from complexity, not from lack of features. Every field you add is a field someone will skip. Every checkbox you create is one that will remain empty. The six-field version I described above covers roughly ninety percent of what I actually need when I am looking back at old experiments. The other ten percent lives in the notes field and in the git history. If you are starting a new project, try this for two weeks before adding anything. I guarantee you will feel the urge to add columns. Resist it. The friction of maintaining fewer fields is almost always worth the loss of convenience from not having structured search. Most of the time you are not searching for anything specific. You are just trying to remember what you tried last Tuesday, and the date column handles that. There is no download link because there is nothing to download. The tool is a file format and a habit. The hardest part is not the format. It is keeping the habit when you are under deadline pressure and the journal feels like bureaucracy. It is not bureaucracy. It is the only reason you will know whether that model worked by accident or by design.
