Don’t Just Document the Process—Document the Why
Policies and procedures become far more useful when you preserve the reasoning, history, and lessons that shaped them.
Many companies are pretty good at updating documents, but poor at preserving the context of those documents. A process gets revised, a policy gets changed, but the documentation has no record of why the change was made (or even that there was a change in some cases). Months or years later, someone will ask “why do we do it this way?” And there is no answer. Or, worse, because no one remembers the answer, you go back and do it the old way again, creating the same problem all over again to be discovered later.
When the “why” is missing, organizations repeat mistakes and lose confidence in their own policies and systems. Part of institutional knowledge isn’t just documenting the how, but also the why, and the history of lessons learned.
What This Really Means
What caused this to surface in my consciousness and lead to an article was actually something entirely unrelated: vibe coding. I was sitting here last week vibe coding away to build some new automations on our private server, and I noticed that Cursor (my vibe coding software) was documenting what it was doing and why after it made changes to our code. I asked it why, and it told me that it keeps these “README” files and similar documentation for each individual process so that it can refer back to them later and understand not only what the process is, but all of the history that led to that process being how it is. That immediately made sense to me and popped out as a common problem for companies and organizations. Even at the labor union in which I served as an executive, we were fantastic at documenting our policies and processes, and even kept records of when they were changed, but if you wanted to know why they were changed, you had to go digging through all of the meeting minutes and figure it out yourself.
When we’re making changes, we should be thoroughly documenting the reasons behind those changes for future reference.
What changed?
Why was it changed?
When was it changed?
Who made that decision and approved it?
What original problem drove the change?
What alternatives were already tried or considered and discarded?
This isn’t about creating a mountain of paperwork and making our documents three times bigger. It’s about ensuring that we don’t lose all of that knowledge and wisdom and make the same mistakes again.
Why This Matters So Much
There are actually a whole lot of reasons to do this, so let’s cover them all!
Preserves Institutional Knowledge
Let’s be honest, teams change over time. Managers leave. People swap roles or get promoted. Even you will someday be gone from your own business. The only way to ensure that future people working in these systems know why things are done the way that they are is to document the why so that those future people have something to refer back to. Otherwise all institutional knowledge is just a lost employee away from being obscured by the fog of time.
Prevents Repeated Debates
How many times have you had a debate with your team and you had this sneaking feeling in the back of your mind that you’ve had this debate several times before? This is not an uncommon experience.
Typically what happens is that a new team member comes on, and they have this great new idea of how to do things! They present the idea and it spurs debate. But the thing is, this isn’t a new idea. It’s actually how you used to do it years ago! But because memories are short, and the people may have changed, you forget all about that, or you at least forget why things were changed. Now you’re in the middle of this discussion, and even though you know that you changed it years ago for a valid reason, you can’t remember for the life of you what that reasoning was. It’s hard to defend policy when you don’t even remember why the policy exists.
Good documentation saves you from this mess. You just go back and look at the documents, and you can see the whole history of what happened and why you made the change that you did. Debate short-circuited, time and frustration saved.
Improves Adoption and Compliance
Yes, every employee should just follow the policies and procedures without needing to have them justified. That’s literally what they’re paid to do. But let’s all just be honest about human nature: people are far more likely to follow the rules if the rules make sense to them.
“Because I said so” may be a way to end an argument with a child, but it doesn’t work too well on your Senior PM. Context is what creates buy-in. When you can explain that the policy was put in place after a prior lawsuit and recommendations from your general counsel, everyone falls in line pretty quickly. Nobody wants to deal with litigation.
Makes Future Updates Easier
When you have all of your history and reasoning documented, it’s a lot easier when it comes time to update that process or policy in the future. That future you, several years down the line, will be able to look at your documentation and remember everything that has already been tried and didn’t work out, and you can determine whether the reasoning that you had for the current system still applies. Sometimes things change, so just because the old way didn’t work before doesn’t mean that it’s still a bad idea. You might look at the old reasoning and determine that due to new technology, for example, the old problem can be easily programmed away and you revert to how you used to do things. But that’s only possible if you have documentation of every thought and decision.
Helps With Risk Mitigation
Do you have any idea how thrilled your attorney will be if you get sued because of a policy or process and you can drop a full record of the why on their desk? This is legal defense gold. You essentially already have counterarguments prepared for every alternative that the plaintiff suggests you should have used. Lawsuits have a way of vanishing when you have over-documented things and opposing counsel realizes that they’re not going up against amateurs.
Reduces Workarounds and Misinterpretations
When people don’t have a reason for why things are done, they tend to invent their own reasons in their minds. And when they don’t like the policy to start with, the reasons that their mind can conjure up tend to be the kinds of reasons that don’t sound very reasonable.
This typically leads to employees ignoring the policy or process because they think it’s poorly reasoned or just outdated, and they create a workaround themselves to do it differently in a way that makes more sense to them. Of course, in reality, you probably already tried the workaround way in the past, and it failed and was replaced for good reason. If an employee understands that, they are a lot less likely to go their own way.
What Happens in the Absence of Historical Understanding
When your team doesn’t have all of that documentation memorializing the why and the history, every process and policy can start to feel arbitrary and unnecessary. Employees question the value of compliance, and it may be subconscious, but they start to undo the very controls and safeguards that you have diligently built into your business over a period of many years.
This just leads to a less efficient and riskier business. Which, of course, is defeating the entire purpose of having policies and procedures in the first place. So unless you want all of your work to document everything to be for naught, then you also need to document the why so that the wisdom of your documents shines through.
An Example
Let’s look at a real-world example from my own business. Years ago, probably a decade ago now, we had an owner terminate management. As most property managers do, we transferred the security deposit to the owner at the time of termination and notified the tenant. A year or two went by. Suddenly we get a demand letter from an attorney representing that tenant. The tenant had recently moved out of the property, and the landlord didn’t return their deposit. The tenant was trying to hold us accountable for it, because we originally accepted the deposit when we were managing the property, and the tenant’s attorney was arguing that we were negligent to transfer that deposit to a layman landlord who doesn’t have a real estate license and clearly didn’t follow state security deposit law.
As a result, our then-attorney changed our lease language: from now on, if management terminates mid-lease, the security deposit gets returned to the tenant in full. The landlord not having a security deposit anymore is not our problem. That’s a problem for the landlord to solve with the tenant directly after management terminates, but we have eliminated our liability risk.
Years went by and we had another landlord wanting to terminate mid-lease. Of course, he had never read the PMA, so he didn’t realize the security deposit would be returned to the tenant, and he got quite irate about that and started threatening litigation.
It was damned helpful to be able to explain our policy to both him and our new attorney years later because we knew exactly what had led to it (and the fact that we had ended up paying out something like $3k to settle the case). A lawsuit was averted, because our reasoning was sound, and our documents were unambiguous.
What Good Documentation Looks Like
This documentation doesn’t have to be a mountain of new paperwork, because I know some of you are already cringing at the idea of more writing. This can be very lightweight and compact.
Documentation should consist of a few things:
A revision log at the beginning of your manuals showing what revision you’re on and when the changes were all made
A notation next to the actual changed sections in the manual; traditionally, this is done by a solid line to the left of the text in the document
Put the rationale and history in a footnote right there in the document, or have a separate Change Summary document that contains it; whatever is easier for you and your team
A notation of who made the change or approved it
A note of what the previous version contained
We don’t need paragraphs and paragraphs of text to explain the change. You just need some simple documentation to jog your memory and have the core rationale and history explained. Simplicity should be valued over thoroughness. Just having any record at all puts you ahead of 99% of other businesses.
Final Thoughts
It’s been refreshing to see the emphasis on documentation in our industry taking off over the last few years. Consultants like PM Pathbuilders have built entire businesses around helping PMs document things, and there have been lots of presentations at conferences talking about the importance of policy and process documentation. But remember, it’s not enough to document what you do; you also need to document what you did, and why you changed it. The documentation of your policy and process is only half the battle. The reasons behind it are what make it durable and useful well into the future.
Clear processes are helpful. Clear processes with preserved context are scalable.
Open to Work
Are you an experienced PM industry employee looking for work? Or are you a PM company or vendor seeking the best talent? Send me your info and I’ll feature it here!
Each week we also feature a Remote Team Member available through VPM Solutions. See this week’s below! Click on the image to get more info:
Newsletter Stats
Here are our statistics for the last 30 days:
73,663 impressions
41.02% open rate
Issue with the highest readership:
“If AI Can Replace 4,000 Tech Workers, What Happens to Property Management?”
8,425 impressions
Looking for Advertisers!
We always have ad slots available for industry vendors. Sign up for an ad or ad package here. Pricing and ad details can also be found at that link. Questions about advertising? Email abio@propertymanagerassist.com or book a time here.
Debate Me
Disagree with my take here? Have a different perspective? There’s nothing I love more than a good debate or even just an intelligent conversation. If you’d like to jump on a podcast recording with me to discuss this topic, please let me know!
The views expressed in this publication are the views of the author only and not any advertisers, sponsors, partners, affiliates, or organizations that the author may be a member of.