Lessons Learned Documentation

I once spent 6 months negotiating a final account as a graduate QS. £2.3M project, £400K in disputed variations. The other QS had better records. We settled for £𝟭𝟴𝟬𝗞. Here's what I learned about documentation: The client's QS walked into the meeting with a folder thick as a phone book. Every variation referenced. Every delay photographed. Every instruction timestamped. I had... Excel spreadsheets and some email chains. The painful reality: We both did the same work. We both managed the same changes. But only one of us could prove it. What separated their approach from mine: They built the claim file during the project, not after it. While I was updating cost reports at month-end, they were capturing evidence daily. When negotiation time came, they didn't need to "build a case" - they just opened the file. The lesson that cost me £220K but taught me that:  1. Documentation isn't about compliance. It's about commercial protection.  2. Every day you don't capture what happened is a day you can't defend what you're owed.  3. Final accounts aren't won in the negotiation room. They're won in the daily discipline of recording what actually happened. What's the biggest final account lesson you've learned the hard way? 👇

A senior engineer joined a team I was advising. First week, he spotted a weird workaround in the payment flow. He cleaned it up. Payments broke on a Friday at 4:55 PM. $47K in failed transactions before anyone caught it. The workaround existed because the payment provider times out on large carts. The retry logic caused double charges. The workaround prevented duplicates. Nobody had written that down anywhere. The team learned the same lesson twice. Once in production. Once in the postmortem. Here's the documentation problem most teams don't see: Skip it → institutional knowledge disappears the moment someone leaves. Document everything → shipping slows to a crawl. Docs drift. Reality moves faster than Confluence. The fix is a 3-part minimum documentation standard: The decision — What did we choose? What did we rule out? "We kept the workaround in the payment flow." The reason — Why does this exist? What constraint forced it? "Provider times out on large carts. Retry logic caused duplicate charges." The consequences — What breaks if someone removes this? When to revisit? "If removed, duplicates return. Revisit when provider supports idempotency keys." Three parts. One page. One link in the PR. What to document every time: ✓ Architecture decisions that change the shape of the system ✓ Weird workarounds that look wrong but are right ✓ External constraints — vendors, compliance, rate limits ✓ Public contracts — APIs, events, schemas What to stop documenting: ✗ UI screenshots of interfaces that change weekly ✗ "How to set up the repo" essays nobody updates ✗ Meeting notes with no decisions ✗ Anything that duplicates what the code already says Ship the software. Document the why. Skip the rest.

Why I'm teaching my engineers to fail faster (and document every disaster). My team keeps a "Failure Log." Every crash. Every outage. Every 3 AM page. We document it all. Most teams hide their failures. We showcase them. Once, a junior engineer deleted our production database. The entire thing. Gone. His first instinct? Hide it. Fix it quietly. Hope nobody notices. Instead, he wrote a 3-page post-mortem. Detailed every wrong click. Every missed safeguard. Every assumption that led to disaster. That document? It's now required reading for every new hire. Here's what most engineers don't understand: Your failures are worth more than your successes. At my last couple of companies, I kept meticulous records of failures. Every bug. Every missed deadline. Every architecture decision that backfired. Those notes got me a head start in career progression. Why? Because in my promotion packet, I could show: - 47 prevented outages from lessons learned - $3.2M saved by not repeating past mistakes - 12 junior engineers who avoided my errors The best engineers I know have the longest failure logs. They document: - What broke - Why it broke - What they tried that didn't work - What finally fixed it - How to prevent it next time One Principal engineer at Amazon showed me her failure log. 8 years. 1,200 entries. She called it her "Million Dollar Notebook." Every entry prevented a future disaster. We teach engineers to hide failures. Wrong approach. The engineers who advance fastest? They fail faster. Document better. Share wider. My team's failure log has prevented 23 outages in a year. Each entry includes: - Timestamp - Impact (users affected, revenue lost) - Root cause - Failed solutions - Successful fix - Prevention plan New engineers think this is punishment. Veterans know it's gold. Your failures are your competitive advantage. But only if you document them. Stop hiding your disasters. Start cataloging them. What's the most expensive failure you've turned into a learning opportunity? (What is in your million-dollar notebook?)

💎 How To Track Your Impact (+ free Notion templates). How to document your small and big wins, visualize your work and the incredible impact you've made ↓ We often assume that good work speaks for itself. If we just work hard enough, our work will get noticed and we will be elevated across our career ladder. Yet more often than not, your achievements will get lost somewhere between reorg efforts, new priorities, abandoned initiatives and urgent deadlines. Managers change all the time. You might have a strong relationship with your manager already, but never get a chance to move up the ladder because they have already moved to another team. A new manager, despite all your efforts, often won’t be able to promote you as an internal policy might block any new promotions in their first 6 or 12 months. So you’ll have to start over again. A good way to push back is to have a “brag document” — a running document that lists your small and big achievements, feedback from your managers and colleagues, screenshots of your appraisals and recommendations, along with lessons you’ve learned. It also builds confidence in your abilities and helps you better see your career trajectory. Useful things to include: 🧠 New skills you’ve learned 🏅 New certificates you’ve acquired ⏱️ Impactful projects you’ve leaunched 🧪 Experiments or A/B tests you’ve initiated 🧭 Product metrics you’ve moved 👋 Onboarding sessions you helped with 🚀 Changes you’ve initiated 🗣️ Workshops you’ve conducted 🧑🏫 Mentoring sessions you’ve coached 🌟 Endorsements you’ve received 🤝 Collaboration wins across departments 🧹 How you’ve dealt with design debt 📦 Successful scoping and getting buy-in 🛠️ Tools or systems you’ve introduced 🔧 Bugs or issues you proactively resolved 📣 Coordinating communication in teams 🔮 Lessons you’ve learned 🧯 Conflicts you’ve resolved There are plenty of things that can go in such a document. Typically it’s a simple Notion page or a Google Doc that you set up once and keep updating regularly. One useful habit that can help there is to always update the document after a retrospective session with your team and around a month later. The reason for that is that you’ll need to accumulate and add concrete evidence and results of the impact of your work. Typically business metrics are lagging metrics, so it will take a while until you get some results. One word of caution: it doesn’t work well if you update in huge and bulky batches as memories become a bit blurry and details get lost. Also, don’t think just about the design work — work also happens outside of the design work as we saw in the list above. Also, as Stephen Kernan noted once, whenever possible, try linking your accomplishments to the career ladder one level above your current role. If you can prove that you’ve been performing at the next level for past 3-6 months, you will make the case for your promotion strong and more obvious. (Useful templates in the comments below ↓)

I've interviewed 50+ senior designers in the last quarter. Two alarming trends emerged: 𝟭. Portfolio paralysis: They can't showcase their best work. 𝟮. Memory fog: They struggle to recall project details from mere months ago. The result? Panic-induced all-nighters piecing together fragmented case studies. 𝗧𝗵𝗲 𝟭𝟬% 𝗦𝗼𝗹𝘂𝘁𝗶𝗼𝗻 👇 Implement this habit now: • Dedicate 10% of your week to documenting your design journey. • That's just 4 hours for a standard work week. • The payoff? Weeks of future stress eliminated. 𝗬𝗼𝘂𝗿 𝗗𝗼𝗰𝘂𝗺𝗲𝗻𝘁𝗮𝘁𝗶𝗼𝗻 𝗧𝗼𝗼𝗹𝗸𝗶𝘁: 𝟭. Daily Micro-Journaling (5 minutes) • Capture key decisions • Note stakeholder feedback • Record "aha" moments 𝟮. Weekly Summaries (30 minutes) • Outline sprint accomplishments • Highlight major pivots • Archive key artifacts 𝟯. Project Milestones (1 hour) • Synthesize learnings • Curate a "greatest hits" collection • Record quantitative & qualitative impact 𝗣𝗿𝗼 𝗧𝗶𝗽: Set up a Notion template or FigJam board. Make documentation frictionless. 𝗧𝗵𝗲 𝗖𝗼𝗺𝗽𝗼𝘂𝗻𝗱 𝗘𝗳𝗳𝗲𝗰𝘁 👇 Imagine this: 6 months from now, you have: • 26 concise weekly summaries • 130+ daily entries • A curated showcase of your best work You're not just prepared for job hunting. You're primed for: • Promotions • Speaking engagements • Mentorship opportunities Remember: Your future self will thank you. Your future hiring manager will be impressed. Don't let your best work fade into memory. Document, curate, and shine. ----- I've posted about this issue recently & had some great feedback & conversations. 💬 ----- #design #tech #ux #productdesign #careers

Career advice I’d give my younger self: Keep a record of your wins Document your accomplishments as you go - not just what you did, but the real impact. (Keep this in a personal repository, not at work.) Most of us move from project to project, thinking we’ll remember the details when we need them. Then, when it’s time for a job search or a performance review, we struggle to articulate our impact. Instead, whenever you start a new project, ask yourself: “How will my future self talk about this?” Think in terms of a story - a problem worth solving, a difficult and challenging solution, and a meaningful transformation. You don’t have to wait until the project is finished to start writing it. Step 1: The problem What problem are you solving? A (business) problem worth solving has the problem itself, which lead to symptoms that, if they aren't addressed, can lead to disaster. For example, you might be replacing a legacy workflow. The old workflow is slow and includes manual steps. This results in errors and customer dissatisfaction, which leads to financial risk (due to errors) and churn, resulting in stagnant revenue and declining market share. You'll get more insight over time, but just start at the start. Write down what you know. Step 2: Document the outcomes you (or your leadership) are expecting or hoping for You may not know the final impact yet, but you have a hypothesis. What will change if your project succeeds? More revenue? Higher efficiency? Customer satisfaction improvements? Write that down. The transformation is often the opposite of the problem: if revenue is stagnant, the goal is growth. If churn is rising, the goal is retention. Define the ideal outcome early. Step 3: Capture the key components of the solution As technologists, we naturally document what we built. That’s fine, but remember—hiring managers and execs care less about features and more about impact. And how you collaborated and persuaded stakeholders to create and keep alignment. Step 4: Update your story as you go As your project progresses, go back and update: ✔ What you learned about the real problem ✔ Changes in your approach ✔ The actual results once customers started using your solution Often, the results blossom in unexpected ways - leading to social proof like customer stories, awards, or internal recognition. Capture those. These stories become the basis of a resume that gets interviews and they're great for performance reviews.

🚨 𝗜 𝗷𝘂𝘀𝘁 𝗿𝗲𝘃𝗶𝗲𝘄𝗲𝗱 𝟱𝟬+ 𝗙𝗗𝗔 𝘄𝗮𝗿𝗻𝗶𝗻𝗴 𝗹𝗲𝘁𝘁𝗲𝗿𝘀 𝗳𝗿𝗼𝗺 𝘁𝗵𝗲 𝗽𝗮𝘀𝘁 𝗾𝘂𝗮𝗿𝘁𝗲𝗿. One pattern jumped out immediately and it wasn’t about complex tech failures or multi-million-dollar systems It was about something far simpler - 𝗗𝗼𝗰𝘂𝗺𝗲𝗻𝘁𝗮𝘁𝗶𝗼𝗻 Startups weren’t getting flagged because their devices didn’t work. They were getting flagged because they couldn’t prove they worked. If it is not recorded it did not happen! • Missing design history files • Incomplete complaint investigations • Vague CAPA records    All the “boring” stuff that feels like a distraction when you’re sprinting to market. Every shortcut you take with documentation becomes a detour later. 𝗧𝗵𝗿𝗲𝗲 𝘁𝗵𝗶𝗻𝗴𝘀 𝗜 𝘁𝗲𝗹𝗹 𝗲𝘃𝗲𝗿𝘆 𝗠𝗲𝗱𝗧𝗲𝗰𝗵 𝘀𝘁𝗮𝗿𝘁𝘂𝗽 𝗜 𝘄𝗼𝗿𝗸 𝘄𝗶𝘁𝗵 👇 → Document in real time — not in hindsight → Teach your team: “If it’s not documented, it didn’t happen” → Build quality into your process from day one The winners in MedTech right now aren’t the ones with the biggest compliance budgets, they’re the ones who treat documentation as a competitive advantage Because your regulatory foundation is either your launch pad or your bottleneck. Founders in MedTech: What’s been your toughest challenge keeping documentation consistent while moving fast?

Failing well unlocks growth. But setbacks test one's learning capacity. Failures are part of any journey which often stays unseen or unnoticed. They usually do not define the journey as success does. What is crucial though are the lessons that are extracted after the fall. Converting failure into rocket fuel for success demands methodical review, identifying contributing factors dispassionately and gathering external perspectives revealing overlooked weak spots. This post-mortem fuels a shift from self-defeat to self-education. Setbacks become masterclasses in success rather than endings. Each setback strengthens judgment to refine strategies and evade future failures. How to extract lessons from failures: Conduct autopsy reviews Surgically analyze contributing factors without self-judgment. Embrace external perspectives revealing overlooked issues. This failure autopsy supplies data to update approaches. Shift mindsets from defeat to education Reframe downfalls as invaluable real-time masterclasses rather than endings. Develop resilience by extracting lessons that enrich strategies to avoid repeats. Set evolved goals informed by new wisdom. Make changes and experiment Leverage autopsy findings to re-calibrate tactics and plans. Then test new methods unafraid. Experimentation unearths workarounds while preventing strategic stagnation. Share learned lessons Document and share key takeaways openly with others. This builds organizational learning capacity as teams gain from your trials. Failing well unlocks innovation. In closing, remarkable success links directly to one’s ability to learn from failures faced. Growth flows from informed adjustments, community support and unbroken self-belief. Mine your setbacks for game-changing lessons. For within every downfall, the seeds of transcendence await rediscovery by those bold enough to rise.

Have you ever wondered why the same problems can resurface even after you have addressed them? The biggest risks for organisations may not be in what they forget but in how quickly they forget. I once worked with a corporate client that suffered a major disruption because their systems were unable to handle a sudden surge in customer demand. We increased server capacity and restored service, but we did not document the lesson. A few months later, a similar surge occurred. Without a clear record of what had been done previously, the issue repeated itself with even more serious consequences. The lesson here is not about ignorance; it is about forgetting. Many organisations work hard to learn from setbacks, crises or mistakes. They hold post-mortem sessions, extract lessons and draft new policies. Yet as time passes, memory fades and urgency softens. Teams move on, leaders change, and priorities shift. Some researchers call this “Organisational Amnesia," a gradual erosion of collective memory. It shows up quietly. People find themselves asking: - Why are we still fighting this issue? - Why did we remove that control? - Why did we stop doing what we agreed worked? The faster you grow, the greater the risk of repeating old mistakes. To counter this: 1. Write down your lessons. Record not just actions, but the context and rationale behind them. 2. Revisit them routinely. Build them into your operating rhythms rather than leaving them to occasional reviews. 3. Make them visible. Culture is not merely what we say; it is what we remember and reinforce. Good leadership is about learning fast and remembering well. Collective memory is part of operational discipline, too. Have you seen this kind of amnesia in your organisation? I would welcome your insights on how you ensure lessons are not lost.

One lesson I’ve learned working as a SOC analyst: if it’s not documented, it didn’t happen. In the middle of incidents, we’re busy — analyzing alerts, escalating tickets, checking logs. But when the dust settles, documentation is what makes all the difference. Here’s why clear documentation matters: Continuity: Another analyst should be able to pick up where you left off without confusion. Accountability: Well-written notes show exactly what was investigated and why. Improvement: Past incidents become future learning material when documented properly. Defense: In case of audits or legal reviews, documentation is evidence that the SOC took the right steps. A simple framework I use when documenting: What happened? (Alert summary) What was done? (Steps taken) What was found? (Evidence, results) What’s next? (Escalation, closure, lessons learned) Takeaway: Documentation isn’t “extra work.” It’s part of the defense strategy. Clear, structured notes protect the organization just as much as firewalls and SIEM rules. How do you approach documenting cases in your role? #CyberSecurity #SOC #Documentation #IncidentResponse #SoftSkills