Introduction: Documentation as a Cultural Signal
In many engineering teams, documentation is treated as an afterthought—something we write when there is time, if there is time. Code reviews are systematic, CI pipelines are automated, testing culture is discussed and refined. Yet documentation, which shapes how teams share knowledge and coordinate decisions, is often left to individual discipline and goodwill.
But documentation is not just a collection of text files. It is a cultural signal.
How teams write (and maintain) documentation communicates what they value:
- Whether knowledge is shared or siloed
- Whether onboarding is a guided process or a form of survival
- Whether decisions are remembered or rediscovered
- Whether the product’s reality matches its documentation—or not
When documentation decays, trust decays with it. And trust is expensive to regain.
The challenge, then, is not simply “writing more documentation,” but building a culture where documentation is treated as a part of the product itself—reviewed, maintained, and continuously improved alongside code.
This is where treating documentation quality as a first-class citizen in CI/CD pipelines becomes transformative.
When Broken Links Become Broken Trust
Documentation is more than a reference—it is a promise.
When we publish architecture diagrams, onboarding guides, operational runbooks, or product specifications, we are making a statement to our teammates:
“This is how the system works. You can rely on this.”
So what happens when a link is broken?
Or when a README references outdated behavior?
Or when a guide includes instructions that no longer reflect reality?
People stop trusting the documentation.
And once trust is gone, even perfectly correct documentation will be questioned.
Teams start asking around instead of reading.
Knowledge becomes interpersonal again.
The organization quietly shifts from a shared knowledge model to a tribal knowledge model.
This has real costs:
- Onboarding slows down
- Decision-making becomes opaque
- Past lessons are lost and re-learned
- Review and collaboration rely on memory instead of artifacts
This is why documentation quality is not a matter of neatness.
It is a matter of organizational reliability.
Broken links are not just broken links.
Broken links are broken trust.
Why Documentation is Hard to Keep Healthy
If we agree that documentation matters, the next question is:
Why is it so hard to keep documentation healthy?
Unlike code, documentation often has no single owner.
It sits in a gray area between product, engineering, design, support, and operations.
Everyone uses it.
Everyone benefits from it.
But no one is explicitly responsible for maintaining it.
And unlike code, documentation does not fail loudly.
There is no compiler complaining.
No CI job turning red.
No stack trace when the meaning shifts or when a sentence becomes outdated.
Documentation decays silently.
Because of this, teams tend to rely on good intentions:
- “Someone will update it.”
- “We’ll fix it during the next sprint.”
- “We’ll remember this decision anyway.”
But people don’t remember.
Teams grow. People leave. Systems evolve.
Without intentional mechanisms for maintenance, documentation inevitably drifts away from reality.
The challenge is not that teams don’t care.
The challenge is that documentation lacks the same structural safeguards that protect code quality.
To keep documentation healthy, we need systems—not just effort.
Treat Documentation Like Code: Enter Linting
If documentation decays because it lacks structural safeguards,
then the solution is not “more effort,” but better infrastructure.
We don’t maintain code quality through motivation or goodwill.
We maintain it through systems:
- Code reviews
- Static analysis
- Typed contracts
- CI pipelines
- Test suites
These mechanisms don’t replace human judgment—they support it.
They make the healthy behavior the default behavior.
We can apply the same thinking to documentation.
If we want our documentation to stay reliable,
we need tools that:
- Detect inconsistencies early
- Make issues visible, not silent
- Encourage correction at the moment of change
- Keep shared language stable across contributors
This is where documentation linting comes in.
Linting documentation is not about enforcing perfection.
It’s about protecting shared understanding.
It allows teams to shift from
“we update documentation when we remember”
to
“documentation accuracy is continuously verified.”
Not tighter control.
Just better support for the culture we want to create.
Introducing gomarklint: A Practical Linter for Markdown
When we introduced linting into our documentation workflow, we didn’t want a tool that enforced aesthetics, personal style, or formatting fads.
We wanted something simpler and more fundamental:
A tool that helps teams keep documentation trustworthy.
This led to gomarklint — a Markdown linter designed to protect the structural integrity of documentation, without dictating how people should write.
gomarklint focuses on things that directly affect shared understanding:
- Detecting broken or missing links
- Ensuring heading levels follow a coherent structure
- Highlighting ambiguous references or placeholder text
- Surfacing subtle inconsistencies that accumulate over time
In other words, it focuses on the parts of documentation that erode trust when they decay.
- It is intentionally minimal:
- No heavy configuration
- No stylistic judgment
- No unnecessary rules
Just the core checks that preserve reliability and continuity across contributors.
This matters because a tool influences culture.
If the tool is heavy, people avoid using it.
If it is lightweight and aligned with purpose, it becomes part of everyday practice.
gomarklint was built to be that kind of tool:
Not restrictive.
Just supportive.
Not opinionated.
Just reliable.
A small guardrail that keeps the path clear.
Repository: https://github.com/shinagawa-web/gomarklint
How Our Review Culture Changed After Adoption
When we added documentation linting to our workflow, the most meaningful change was not the number of issues caught.
It was the shift in how the team talked about documentation.
Before:
- Documentation updates were “nice to have”
- Reviewers focused almost entirely on code
- Outdated sections were noticed only when they caused confusion
- Small inconsistencies were tolerated because fixing them felt optional
After introducing gomarklint:
- Documentation changes became part of the review conversation
- Reviewers felt permission to point out unclear naming, missing references, or outdated instructions
- Updating documentation became a natural part of making changes—not an afterthought
- The threshold for “good enough” rose, but without adding pressure or judgment
The presence of linting changed the default expectation:
Documentation should reflect reality.
And because the tool handles detection, the emotional weight disappears.
Feedback shifted from:
“Why didn’t you update this?”
to
“The linter caught this—let’s align it.”
This matters.
Not because it catches errors, but because it reframes ownership:
Documentation is something the team maintains, together.
Not heroic effort.
Not personal responsibility.
Just shared care, supported by lightweight automation.
Conclusion: Documentation Quality is Organizational Health
Documentation is not just a record of what we build.
It is a reflection of how we work.
When documentation is reliable, knowledge is shared.
Onboarding is smooth.
Decisions have continuity.
Teams move with confidence.
When it decays, the opposite happens—slowly, quietly, and expensively.
Treating documentation as part of the product is not about increasing process or control.
It is about supporting the culture we want to have:
A culture where knowledge is shared.
Where change is understood.
Where trust is maintained.
Linting is not the solution by itself.
But it is a small, powerful guardrail—one that keeps our shared understanding aligned with reality.
Documentation quality is not a matter of neatness.
It is a matter of organizational health.
And when we care for it intentionally,
the entire team feels the difference.
If you'd like to explore the tool mentioned in this article:
gomarklint
https://github.com/shinagawa-web/gomarklint
Top comments (0)