My Philosophy of Documentation

Documentation, oh documentation
How many use your "outdated" reputation as an excuse not to write you at all?

Hi. Do you write documentation?
If you do, how did you start?

I still remember the first time I was asked to write documentation at work.
Back then, my manager wasn’t exactly encouraging engineers to write docs.

Why?
Probably because documentation needs regular updates—or it goes stale.
Worse, outdated or conflicting docs can create a mess that’s more harmful than helpful.

Would you have just accepted that answer?
I couldn’t.

The manager wasn’t banning documentation—just not promoting it.
That’s a big difference. And I guess I’m the kind of person who likes to push the edges of what’s allowed.

That’s when I began a line of thought I’d later call:
What documentation means to software engineering.

Start with “Software Engineering”#

Let’s break it down: documentation, software engineering, meaning.

Some parts are abstract—too fuzzy to start with—so I began with the more concrete one: “Software engineering.”

Have you ever stopped to ask: What exactly is software engineering?

In my search, I found a quote I liked from David Lorge Parnas, pioneer of information hiding:

“Software engineering is the multi-person development of multi-version programs.”

In other words, software engineering is building evolving programs as a team.
Even solo developers collaborate—with their past, present, and future selves.

So being a software engineer isn’t just about writing code.
It’s about doing it well in a world of shifting versions and many contributors.

Then, Let’s Talk About Documentation#

So what is documentation?

Some say self-documenting code is a core skill—and a difference between developers and engineers.
But that still doesn’t answer the question.

In practice, documentation comes in many forms—READMEs, API docs, test reports, specs, diagrams.
It can be text, images, tables, flowcharts, or a mix.

In the context of software engineering, documentation connects directly to its core nature:
multi-person, multi-version collaboration.

Where people and code are constantly evolving, documentation becomes a bridge across time and turnover.

Maybe that’s its true meaning in software engineering.

From Concept to Strategy#

I know this sounds abstract.
But for me, laying out a thought process helps me ground decisions in principles—not just instinct.

In my last job, I convinced my manager to stop blocking docs by lowering the cost of writing them.
But I still felt I was operating on gut feel.

Yes, I could decide case by case.
Yes, I could persuade stakeholders.
But did I have a documentation investment strategy?

Especially with limited time—how do you prioritize what’s worth documenting?

So in this job, I wanted a framework that created value for both engineering and the business.
Because not all documentation carries the same weight.

Three Angles to Evaluate Documentation#

While my previous and current managers had different concerns, both cared about efficiency and value.

I broke the problem into three dimensions:

• Lifecycle
  Some docs are short-lived (e.g., project notes); others persist.
  Knowing the expected lifespan clarifies maintenance needs and ownership.

• Frequency of Questions
  The more often something is asked, the more valuable it is to document.
  This saves time and surfaces knowledge gaps.
  If one person becomes a bottleneck, it’s time to scale horizontally by documenting and sharing.

• Risk Level
  Some topics rarely come up—but when they do, mistakes are costly.
  These are like evacuation manuals: seldom used, but must be reliable when needed.

Reducing the Friction of Writing#

Once I knew what to document, the next challenge was how.

I didn’t want to rely on willpower every time.
And I didn’t want to be the only one writing.

So I borrowed from requirement and design review workflows and made documentation a collaborative process:

• Define the purpose before writing
  Who’s it for? When will they read it? What problem does it solve?
  What’s their technical background? What’s in or out of scope?

• Start with an outline, not a full doc
  This makes reviews easier and avoids overwhelming readers.
  It lowers the cost of feedback and encourages early alignment.

• Separate detail from structure
  Focus on the reader’s task. Move tangents or extras to references or FAQs to keep the main flow clean.

Documentation as a Bridge—and a Dialogue#

As I worked on reducing the friction, I realized something unexpected:

Documentation isn’t just an output.
Writing it is a chance to facilitate discussion and build alignment.

Collaborating on outlines or examples uncovers mismatched assumptions.
It turns vague disagreements into something concrete.

Docs become more than knowledge repositories.
They’re tools to drive conversation, challenge assumptions, and align mental models.

In that sense, documenting is just another form of version control—
but for team understanding.

Back to the Original Question#

Hi again.

Do you write documentation?
How did you start?

I no longer ask whether we should document, but rather:
What’s worth documenting?
How do we write meaningfully?
How do we use the process to give teams clarity and direction?

Because documentation isn’t just knowledge transfer—
it’s how we keep that knowledge from staying locked inside overworked experts.

The meaning of documentation in software engineering might lie in the small choices we make:

• What to preserve
• Who to preserve it for
• And how to do it

The sum of those choices is part of what makes us software engineers.

Do I know if this way of thinking will lead me where I want to go?
No.
I didn’t expect it to get me close to a Staff-level role—at least not so soon.

But maybe that’s how it starts.