Writing a “Today I Learned” post worth reading

A "Today I Learned" post is the smallest useful thing a developer can publish. It does not need a big idea, a series plan or a weekend of editing. It needs one fact you did not know this morning, written down clearly enough that someone else can use it this afternoon.

That smallness is also the trap. Because a TIL feels too minor to bother with, people either never write it or write it so quickly that it reads like a note to themselves: a command, a shrug, no context. This post is about the middle ground: a short piece that takes under an hour and is still worth a stranger's click.

Pick one fact, not a topic

The first decision is the most important one. A TIL is about a single fact, and the fact should be specific enough to fit in a sentence. "Git has lots of useful shortcuts" is a topic. "git switch - takes you back to the branch you were on before" is a fact.

A good test: could you put the whole lesson in the title? If you can, you have a TIL. If you need a paragraph just to say what the post is about, you probably have a tutorial, which is a different (and longer) piece of writing.

Facts that make good TILs tend to come from small surprises:

• a flag you found while reading a man page for something else;
• a behaviour that broke your mental model, such as a default you assumed was different;
• a one-line replacement for a script you had been maintaining;
• an error message that turned out to mean something other than what it said.

Start with the moment you learned it

The difference between a TIL and a line in a cheat sheet is context. A reader who lands on your post wants to know whether this fact solves their problem, and the fastest way to tell them is to describe yours.

Two or three sentences are enough. What were you doing? What was annoying about it? For the example above, it might be: "I was reviewing a pull request on one branch and fixing a typo on another, and I kept typing the full branch names to jump back and forth." Anyone who has done the same will recognise themselves and keep reading. Anyone who has not will know this post is not for them, which is also a kindness.

Avoid long scene-setting. If the story is taking more words than the fact, cut it back.

Show it, in a block someone can run

Next comes the example. It should be the smallest thing that demonstrates the fact, and it should run as written. For our git example:

git switch feature/login-form
git switch main
git switch -     # back on feature/login-form
git switch -     # back on main again

Then say, in plain words, what happened: the - argument means "the previously checked-out branch", the same way cd - takes you to the previous directory in most shells. Mentioning the familiar cousin helps the new fact stick, because the reader can hang it on something they already know.

Check the example yourself in a fresh terminal before you publish. It is very easy to paste a command from your history that depended on something you set up an hour earlier.

Say where it stops working

This is the part most TIL posts skip, and it is often the most useful paragraph. Every small trick has edges. Name the ones you know about:

• Version. git switch arrived in Git 2.23. On older versions the same trick works with git checkout -.
• Scope. The dash only remembers one step back. It is a toggle, not a history.
• Surprises. If the previous "branch" was a detached commit, you go back to that commit, not to a branch.

You do not need to be exhaustive. Write down what you checked and say plainly what you did not check. "I have only tried this on Linux" is honest and useful; a reader on another system now knows to test it themselves.

Keep it short, but not bare

A TIL has a natural shape, and it rarely needs more than five parts:

1. A title that states the fact.
2. Two or three sentences about the moment you needed it.
3. A runnable example.
4. One paragraph explaining what is going on.
5. A short list of limits, plus a link to the official documentation.

That last link matters. Your post is the friendly introduction; the documentation is the reference. Pointing to it tells readers where to go when your post runs out, and it gives you a quick way to double-check your own claims before you hit publish.

What you can leave out: a history of the tool, a list of ten other tricks, an apology for the post being short. Short is the point.

Make TILs a habit, not an event

The writers who get the most from TIL posts treat them as a running log rather than a series of announcements. A few habits help:

• Capture the fact the moment it happens. Keep a scratch file open and paste the command and one line of context. You will not remember the context tomorrow.
• Write them in batches. One quiet hour a week can turn three captured facts into three posts.
• Tag them consistently. A til tag, plus one tag for the tool, lets readers browse your small posts as a collection. On WestScript, tags and categories on your blog do this for you.
• Link forward. When a TIL grows into something bigger, write the bigger post and link back to where it started.

Over time, a page of TILs becomes a surprisingly honest record of what you were actually working on, which is more interesting to other developers than a polished portfolio.

Sometimes you sit down to write a TIL and it keeps growing. That is a signal, not a failure. If the fact only makes sense after a long explanation, you may be writing a concept post; we have notes on that in explaining a tricky concept with one small example. If the fact came out of a bad week on a project, the real post may be a post-mortem.

Let the TIL stay small and write the bigger piece separately. Readers who want the quick fact will thank you, and readers who want the full story will find it one link away.

If you write on WestScript and want to know how tags, categories and feeds work on your blog, the features page has the details, and the help page covers the rest.