Know The Hidden Secrets of Documentation (Career Booster)
And why working on legacy projects without documentation is like playing Dark Souls.
Hey there,
One of my favorite games of all time is Dark Souls (I know, very original).
Dark Souls is what us oldies (30 year-olds 👴👴) used to play before Elden Ring came along and turned the formula into dodge 700 attacks from this one boss that spins around constantly while a choir chants menacingly in a gibberish language and you die if you get hit once.
If you go back to it today, by modern game standards, Dark Souls is slow. Dare I say, boring, even?
Yet, it was still renowned for its difficulty.
Why, you might ask?
Well, the developers for whatever reason pretty much refused to explain a single thing.
In the game you can choose to go places you have no business being. Statistics that alter your game experience are unexplained. Mistakes are punished (heavily).
The true difficulty of Dark Souls is simple: knowledge.
The game is so much more approachable if you passed the knowledge check. Easy, even.
And that’s exactly what approaching a new codebase is like.
The truth of documentation.
Undocumented code is a massive wall to scale, and the wall only grows bigger the more complex it is.
Everyone feels this way: we all just want to pass the knowledge check.
And facilitating others passing the check is what makes good documentation (and what makes you stand out).
Remember when we talked about code that haunts you? Well, undocumented code is like being cursed in Dark Souls, losing 50% of your health and not knowing you need a Purging Stone to remove it.
Documentation is “real work”.
Many junior developers see documentation as that thing you do after the "real work" is done.
"The code is self-documenting," they say, confidence high.
I recently had to modify a feature in a codebase where the only documentation was a single comment that read: "VERIFY IF THIS IS NECESSARY"
Spoiler alert: I had no clue if it was necessary. I lacked a lot of context. Feeling pressured on time and running into something like that sucks.
Documentation isn't just extra work.
It's your code's user manual, your team's knowledge base, and (honestly) a massive career opportunity that most early-career developers completely miss.
It matters more than you think.
Here’s why:
It shows you think about others (major points)
Makes your code more maintainable (remember Enduring Code?)
Helps you stand out in code reviews
Acts as your own debugging aid months later
So how do we write documentation that actually helps people?
Three Levels of Documentation Mastery
Code-Level
This is your front-line documentation, right there in the code.
Remember how we talked about functions that do one thing? Well, you need to explain that one thing clearly.
Practical steps:
Write docstrings that explain WHY, not just WHAT
Include example usage for non-obvious functions
Document assumptions (what might break this?)
Explain any "magic numbers" (preferably through just naming them) or complex logic
Instead of this:
Write this:
An important note is to avoid overdoing it. Don’t just add redundant comments that provide nothing of value. That’s just clutter.
Project-Level
This is your project's welcome mat.
Think of it as the "Hello, future developer!" message.
Essential elements:
Project purpose (what problem does the solution solve?)
Setup instructions (make them copy-paste ready, and PLEASE keep them updated)
Basic usage examples
Common gotchas or known issues
Where to find more detailed documentation
Don't make others play detective with your code.
Domain-Level
This is where you document the bigger picture:
Architecture decisions
System interactions
The ecosystem the project exists in
Complex workflows and processes
Patterns and best practices
Remember those "why did we do it this way?" moments we talked about in previous newsletters? This is where you prevent them.
Start Today: Your Documentation Journey
Pick ONE of these to start with:
Add proper Code-Level docstrings to the functions you're currently working on
Create a basic README or other document for Project-Level documentation
Document something deeper on the Domain-Level, like a technical reason for a decision, or one of the most used workflows of the solution
BUT start small.
You're not writing a novel (yet), you're leaving breadcrumbs for future developers.
Remember: "I wish I had documented this better when I wrote it." is a common complaint.
You’ll hear it often.
Don't wait to learn the lesson the hard way.
Start treating documentation as part of your code, not as an afterthought.
See you next Tuesday!
PS... Did this newsletter help demystify documentation? Share it with a fellow developer who might be struggling with their code's documentation. Each share helps more developers write code that tells its story clearly!