The Psychology of Bad Code Part 6 – Avoiding Documentation

This is a series. The first blog post is here, #2, #3, #4, #5, and this is the sixth.

The behaviour: Avoiding Documentation

What this looks like in the real world

• Full-on not writing documentation that is mandated as part of project requirements, deciding intentionally not to do a mandatory part of your job
• Skipping some documentation because “the code is self-explanatory”
• Writing just enough comments to get by, or none at all
• Not updating docs when things change, even though you know you should
• Relying on ‘corporate memory’ or office knowledge instead of writing things down
• Putting off documentation until “later”… but later is never

The cause is often cultural:

• You see no one being rewarded for this work, so why would you do it?
• No one checks that it’s done or asks for it
• It’s not part of the formal process for projects, or it’s a ‘checkmark’
• You suspect no one is reading what you write
• You don’t see the value in the act of writing the doc itself (how it clarifies thought and ideas)

I’ve worked at places where I KNEW no one was reading the docs I wrote. I did eventually learn that writing a doc gave me value, personally, but that took some maturity on my part. I also moved onto places where people valued such work, and it was very motivating to do the work when I knew my team needed it. If we make people feel like it doesn’t add value, then it doesn’t get done.

Behavioural biases at play

• Effort discounting: We avoid tasks that feel like high effort with low immediate reward. The value of documentation is usually seen later or not seen at all by the person who wrote it. It’s not the same as pushing code that fixes a bug in production; immediate gratification.
• Tragedy of the commons: Everyone benefits from good documentation, but no one feels individually responsible for maintaining it. If you skip out on doing your part, and everyone else does theirs, the org still wins. If most people avoid this responsibility, someone needs to pick up the slack, and they don’t usually get recognized for it. I’ve never seen anyone except technical writers get promoted for writing documentation.
• Bandwagon Effect: If everyone else is avoiding it, it feels safer to follow. In this case, if everyone is skimping on documentation, you know you won’t get in trouble either.

Documentation doesn’t feel urgent. It is generally not considered an exciting part of the job. And most of the time, no one asks about it

Why this behaviour makes sense in the moment

Documentation is rarely what we’re measured on. And it often feels low priority compared to coding. Management and ‘the business’ want features, bug fixes, meet deadlines. They don’t usually care if your code is easy to read (even if your teammates do) or if it’s easy or hard to onboard a new team member. It matters, but not to the people who reward us. Or maybe I’m wrong? You tell me what it’s like where you work.

On top of that:

• Writing good documentation takes time
• It requires context switching, and it’s not necessarily a skill you’re good at or enjoy
• It may feel redundant (the whole team knows this already), low value (no one is going to read this), or low priority (I don’t have time for this now, I will do it later)

Skipping it may feel efficient. Because in the short term, maybe it is. Or sometimes, even in the long term. I’m not trying to be negative here; I’m trying to be realistic. I’ve worked at multiple places where they hardly ever read the answers to the security questionnaires, and it made me want to pull my hair out. “The security team just doesn’t have time to read all of them.” Me: you think the devs had time to ANSWER THEM?!?!??!!? It takes more time to answer than read the answers. To me, a situation like that shows a lack of respect for your colleagues, but obviously I have strong feelings about this, anyway… Obviously as a dev I personally did this bad behavior, a lot.

The security risk

Missing or outdated documentation creates invisible risk.

• Developers don’t know the intended behavior of a system, and neither does the security team
• Security assumptions are not written down, and some of them may be completely unacceptable – we just don’t know
• Trust boundaries are unclear, undocumented, and therefore potentially (probably) also undefended
• Edge cases and failure modes are undocumented (unless you’ve had a pentest, then some of them are and you’ve outsourced some of the documentation, and outsourcing what you can is perfectly okay but it’s kinda expensive)

What happens is there are no docs when you need them? People guess.

And when developers guess, they usually guess based on:

• What’s easiest
• What worked last time
• What looks right

Not necessarily what is secure. Especially if they haven’t had training (which most devs haven’t).

Maybe also:

• Security controls may be removed because no one knows why they were there in the first place
• Logging, validation, and other checks could quietly disappear over time, because the original requirements are gone
• New developers make changes without understanding the full system, especially the overall risk of the system and/or data

This is how systems slowly drift into insecure states. I call this ‘security drift’.

Solutions:

Training

You can’t train someone to care about documentation if the system/org doesn’t value it.

If documentation:

• Isn’t required
• Isn’t reviewed/read/used
• Isn’t rewarded

It will not get done consistently. Why would it? It doesn’t matter how many times we say “documentation is important” if we show them over and over that it is not true.

This time the training needs to be for management, security, the project team, and basically everyone except the devs. Management needs to create processes to reward and acknowledge documentation work. Project and security teams need to only ask for documentation they actually require and will use. Make the work have value, and they will do it.

Secure Defaults

Make documentation part of the definition of done. If you can add some sort of ‘check’ that it’s submitted (and completed, not just an empty doc), that might help.

Create templates that fill as much as possible, so time is not wasted.

Do interviews instead of questionnaires if possible. I know it takes more time, but you better believe it that the results are superior. And you will build knowledge, trust and relationships.

Environmental Design

Make it easy to document things where work is happening.

• Templates as above
• Prompts in pull requests like:
  “What assumptions does this change make?”
  “What should future developers know?”
• Auto-document whenever possible

I would love to hear ideas from readers about approaches you’ve used that worked and what tools you used to do it.

Friction

If documentation is missing, don’t let it slide.

• Flag missing or outdated docs as soon as you find them, and reward/acknowledge people who flag them
• Require minimal-but-specific documentation for critical/security changes
• If there are no security assumptions, ask why, make this a key field (assuming you’re not doing a threat model, that would be even better). Teach everyone how to answer this question, give examples.

Explain the purpose is preventing bad assumptions, design flaws, and guesswork later. Try to explain the value if given the chance.

Social / Cultural

Recognize and reward good documentation. “Clarity is kindness.”

• Call out clear docs in team meetings (but seriously, do it, don’t just read about it in the blog then not do it)
• Thank people who improve shared knowledge (this can be any knowledge sharing, all of it is good and deserves recognition)
• Treat documentation as part of craftsmanship, part of quality and completeness

Incentives (optional, but powerful)

If you want to go further:

• Track documentation contributions
• Include doc quality in performance discussions
• Surface “doc debt” the same way we surface tech debt
• Include this data in performance reviews (seriously)

What gets measured gets done and seen.

Conclusion

Avoiding documentation isn’t laziness. It’s a predictable response to a system that rewards speed and at the same time ignores long-term investment in clarity. We must recognize and reward what we value, not just pay lip service to it.

When documentation is missing, we don’t stop; we guess. And that’s never good for security. 

Up next: repetitive and lazy code.