Subscribe or follow on X for updates when new posts go live.
I have been developing websites and web application software for a long time. Over the years, I have encountered just about every possible approach companies take to documenting their software. Some rely on formal training manuals. Others depend on internal wikis, ticket comments, or loosely organized notes. Many rely on nothing at all.
What stands out is not the format, but the intent. Some organizations treat documentation as a core asset. Others treat it as an afterthought or something that only exists in people’s heads.
This distinction matters more than most teams realize. Documentation is not just about explaining how a system works. It is about removing ambiguity, reducing risk, and creating a single source of truth that does not require constant human mediation to access.
At its core, documentation tends to fall somewhere on a spectrum between tribal knowledge and explicit knowledge. Understanding that spectrum, and deliberately moving toward explicit knowledge, is one of the most impactful things a software organization can do.
Before going further, it is worth clearly defining the two concepts that shape the rest of this discussion.
Definition
Tribal knowledge is the collective wisdom, information, and insight that exists within a team or organization but is not formally documented. It is passed down through word of mouth, mentorship, and informal interactions.
Characteristics
Undocumented
The knowledge lives in people’s heads rather than in a system that others can reliably access.
Context-dependent
It often includes subtle steps, shortcuts, or assumptions that are never written down but are required for success.
High risk
Tribal knowledge creates single points of failure. When one person leaves, becomes unavailable, or forgets details, that knowledge may be permanently lost. This is commonly referred to as the bus factor.
Potential Risks
A new developer is told to “talk to Jane” to learn how a specific module works. The team depends on Jane’s memory and experience, making the project vulnerable if she were unavailable.
This pattern is extremely common and extremely dangerous. It scales poorly, slows onboarding, and quietly increases operational risk.
Definition
Explicit knowledge is knowledge that is formal, documented, and easy to share. It exists independently of any single person and is accessible to those who need it.
Characteristics
Codified
The information is structured and intentionally written to be stored in manuals, specifications, or knowledge bases.
Accessible
Anyone with the appropriate permissions can find, read, and understand it without scheduling a meeting or interrupting a colleague.
Risk-reducing
Explicit knowledge directly mitigates the bus factor by preserving institutional understanding over time.
The transition from tribal knowledge to explicit knowledge is not theoretical. It is a practical and repeatable process.
After realizing the risk, the team sits with Jane to formalize her knowledge. They document her process in Confluence, including diagrams, setup details, and best practices. This converts her personal expertise into a shared, institutional resource.
This act is often referred to as knowledge codification. It is one of the highest leverage activities a team can perform, yet it is frequently postponed or undervalued.
Documentation failures are rarely caused by individual contributors. They are almost always the result of organizational decisions.
Ultimately, it is management’s responsibility to allocate time, resources, and priority to documentation. If documentation is treated as optional, it will be optional. If it is treated as overhead, it will be skipped.
One of the most common failure modes looks like this:
This is not a people problem. It is a planning problem.
Clear and comprehensive UI specifications help alleviate one of the most common sources of friction in software teams: vague tickets.
A vague ticket forces developers, testers, and product managers into unnecessary conversations just to establish basic expectations. Each conversation becomes a temporary source of truth that lives in someone’s memory rather than in a durable artifact.
A good UI specification reduces that ambiguity upfront.
That said, UI specs are not the point of documentation. They are simply one of the most concrete and practical examples of how explicit knowledge can work in practice.
At its simplest, a UI specification is a list of elements on a page, with each element described by how it behaves when a user interacts with it.
Interaction might include:
The goal is not to describe how the UI looks in poetic detail. The goal is to describe what happens, in what order, and under what conditions.
Element #1
- Click Component:
- Trigger loading state
- Validate input fields
- Execute API request
- Display success message
- Redirect to confirmation screen
This format is intentionally direct. It does not tell a story. It removes interpretation.
You may notice the tone of the steps above. Each action begins with a verb. This is intentional.
When describing user interactions, you should use the imperative mood.
The imperative mood is a grammatical form used to express direct commands, requests, advice, or instructions. It typically uses the base form of a verb and implies the subject without stating it explicitly.
Examples include:
This form is ideal for UI specifications because it clearly communicates expected behavior without ambiguity.
Show Button XYZ in a loading state
Expand the Notes List
Search all text inputs for the word “Bananas”
Each of these steps is:
Avoid long narrative descriptions that bundle multiple behaviors into a single sentence.
The button changes from a green to red color and the list of notes expands downwards after being clicked
This forces the reader to parse intent and sequence. It also makes testing and validation harder.
Also avoid vague or subjectless statements.
Displays loading state
Changes color from green to red
These lack clarity about what is acting and when.
This is an uncomfortable truth for some teams, but it needs to be stated clearly.
Developers should write documentation in a place that is not the codebase.
Code explains how a system is implemented. Documentation explains how a system is supposed to behave.
These are not the same thing.
There is an important caveat here. Developers must be given time to document. Documentation cannot be something done after hours or squeezed into personal time. If no time is allocated, documentation simply will not happen.
This phrase often appears when teams are under-resourced or under pressure.
“The code IS the documentation.”
Just so we are clear, the code is not the documentation.
This idea frustrates nearly everyone who has ever had to understand, test, support, or extend a system they did not personally write.
Imagine asking for the manual for your car and being told:
“Manual? Just look at the engine. The engine IS the manual.”
The engine may reveal how the car works, but it does not tell you how it is intended to be used, what behavior is correct, or what outcomes are expected.
Software is no different.
For a mature and reliable application, documentation typically includes multiple layers, each serving a different purpose.
Common examples include:
In more mature organizations, you may also see:
Not every product needs all of these. The point is that documentation exists to serve different audiences and different needs.
In my opinion, UI specifications are among the most critical documents for developers and testers.
They answer fundamental questions:
A good UI spec removes guesswork. It limits subjective interpretation. It reduces the number of clarifying conversations required to do correct work.
Most importantly, it establishes a shared and explicit source of truth.
The real value of documentation is not elegance or completeness. It is trust.
When documentation is explicit, accessible, and maintained, teams trust that they are building, testing, and supporting the same product.
When documentation is vague or tribal, teams compensate with meetings, messages, and assumptions. Over time, those assumptions diverge, and the product becomes harder to reason about.
UI specs are simply one visible example of a broader principle.
Explicit knowledge scales. Tribal knowledge does not.
Documentation is not busywork. It is not overhead. It is not a luxury reserved for large teams.
Documentation is how organizations convert individual understanding into institutional knowledge.
UI specifications matter because they force clarity. They make behavior explicit. They reduce ambiguity and limit the need to chase the source of truth.
But the larger goal is not better UI specs. The larger goal is a culture of explicit knowledge sharing, where systems are documented well enough that people can act without guessing, interrupting, or assuming.
That is how software scales. Not just technically, but organizationally.