Lessons learned post: writing about a project mistake

If you are writing about a project mistake, a lessons learned post is the form to use. It names what went wrong, shows what it cost, says how you fixed it and states what you would do next time. Keep it to one mistake, told in the order it happened, with a lesson the reader can reuse.

Electrified gives you a page of your own to publish a post like this: make an account and you can write it as an article, with your own topics on it.

Why write about a project mistake at all

A mistake you have understood is useful. Writing it down forces you to separate what happened from what you felt about it. That alone makes the next project better.

It also helps the people who come after you. A teammate who joins in six months can read one post instead of repeating the error. A stranger facing the same choice gets a worked example.

There is a third reason. A written account is a record. Memory rounds off the details, and the details are where the lesson lives: the date, the setting that was wrong, the check nobody ran.

What a lessons learned post should include

Five things, in this order:

• Context. What the project was and what you were trying to do.
• The mistake. One clear statement of what went wrong.
• The impact. What it cost, in time, work or trust.
• The fix. What you did to recover.
• The lesson. What you will do differently, stated as something a reader can act on.

Open with the answer. Put the mistake and the lesson in the first few lines, then walk through the detail. A reader who stops after the first paragraph should still leave with the point.

Pick the right mistake to write about

Not every error makes a good post. Choose one that passes these checks:

• It is finished. You know how it ended.
• You understand the cause, not just the symptom.
• Someone else could plausibly make the same mistake.
• You can describe it without exposing private data or a person's name.

Small mistakes are fine. A missed step in a release, a wrong assumption about a deadline or a test that never ran can teach as much as a failed launch. If you already keep a record of releases, such as the one described in how to write a changelog for your project, you may find the mistake there, with the date attached.

A simple structure: context, mistake, impact, fix, lesson

Use one section for each part. In Electrified's editor, an article has a title and as many sections as it needs, and you start a section with ## and a heading. So the skeleton of your post can be this:

• ## Context: two or three sentences.
• ## The mistake: one plain statement, then the detail.
• ## The impact: what it cost, with real numbers from your own project if you have them.
• ## The fix: the steps you took, in order.
• ## The lesson: the rule you now follow.

Keep each section short. If the impact section runs longer than the fix, you are probably dwelling on the pain instead of the way out.

How to stay honest without blaming people

Honesty means saying what happened. It does not mean assigning fault.

Write about decisions and systems, not individuals. Compare these two lines:

Sam forgot to run the migration.

The migration was a manual step, and nothing reminded us to run it.

The second line is more accurate. It points at the gap that let the error through, and that gap is what the next reader can fix in their own project.

Include your own part. If you made the call, say so. Do not shrink the mistake to make yourself look better, and do not inflate it to look humble. Say what you knew at the time and what you did not.

Leave out anything you cannot back up. If you are not sure of the cause, write "we think" and say why.

Example: a lessons learned post, step by step

Say you ran a small tool for tracking release notes, and you shipped an update that broke a setting for existing users. Here is how the post could go.

Title and opening

Title: We changed a default and broke saved settings. First paragraph: "In one release we changed a default value. Existing users' saved settings no longer matched it, and their pages loaded blank. We found out from a user report. We now test upgrades against old data before every release."

That is the whole post in four sentences. Everything below it is detail.

The sections

Context: what the tool does and who uses it. Mistake: the default changed and no one tested an upgrade from older data. Impact: how long the pages stayed blank and how many reports came in, using only figures you actually have. Fix: you rolled back, wrote a migration and re-released. Lesson: keep a small set of old settings files and run each release against them.

Filing it

In the editor, choose Article, add the title and write the body. The body box has Write and Preview tabs, and the preview looks like the published page, so check it there. Add up to 5 topics, separated by commas, such as lessons learned, release process, testing. Each topic links to a page of every post about it.

Press Save draft first. After the first save the editor tells you it is saved as a draft and that only you can see it until you publish. Read it once more the next day, then press Publish.

Mistakes to avoid when writing it

• Burying the point. Do not make the reader wade through a long story before they learn what went wrong.
• Naming and shaming. It makes the post about a person, not a process.
• A vague lesson. "Communicate more" teaches nothing. "Run each release against saved old settings" does.
• Several mistakes in one post. Pick one. Write another post for the next.
• Invented numbers. If you did not measure it, do not give a figure.
• Leaking private details. Remove customer names, internal addresses and anything you were told in confidence.
• Ending on the apology. End on the change you made.

Plain writing helps here. State the problem first, then work through the fix in order. The writing guides topic page lists what has been published under that heading.

Frequently asked questions

How long should a lessons learned post be?

Long enough to cover context, mistake, impact, fix and lesson, and no longer. A short post with a clear lesson beats a long one that wanders.

Should I name the people involved?

No. Describe the decision or the gap in the process instead. Name yourself if you made the call.

What if I do not know the root cause?

Say so. Write what you know, mark what you suspect and explain what you tried. An honest "we think" is better than a tidy cause you cannot support.

Can I save a draft and finish later?

Yes. On Electrified, a draft is seen only by you until you publish it, and a published post keeps its address. You can also unpublish it back to a draft.

Is one post enough?

One is a fine start. If you write more, each mistake gets its own post, and a shared topic gathers them on one page.

Get started

Pick one finished mistake, write the first paragraph so it holds the whole point, then fill in the five sections. Make an account on Electrified: write about your product, topic or idea on your own page, one article at a time, and let readers follow along.