Documentation can be nice (it's something to point someone to if in a design review it becomes clear we're about to repeat a past mistake), but the best way to

Documentation can be nice (it's something to point someone to if in a design review it becomes clear we're about to repeat a past mistake), but the best way to improve based on lessons learned is to bake them into your team's mechanisms. To describe an example at a previous company from the one I'm at now: I used to work for a startup building a mobile phone network (technically, a Mobile Virtual Network Operator, MVNO, if you care about those distinctions - the point is that phone calls went through our infrastructure). It was very easy in the process of changing someone's account (porting in a phone number, changing a plan, or something like that) for the different IDs from different systems (phone number, phone's serial number, SIM's serial number, billing system ID number) to get out of sync. So, we could have documented how to avoid this, and the document would have sat there with no one reading it. Instead we created a nightly job that went through all our accounts and verified that ID numbers were "as expected." It would output to a slack channel with whatever breakages occurred for us to look into the next day. This program also served as documentation - I could look at it to understand what IDs should match to which systems. My current employer follows the same sort of learn-by-building-mechanisms approach, but at a much larger scale.