Based on a LinkedIn post originally published on 13 February 2026
In the early 1990s, while working for a technology company in southern Brazil, I became responsible for producing the company’s technical newsletter.
This was before modern ticketing systems, searchable knowledge bases, internal portals and widespread internet access.
We supported customers using our business software and the infrastructure on which it operated. Questions and problems arrived through telephone calls, handwritten notes, fax messages and on-site visits.
The objective of the newsletter was practical:
Today, we might call the result a knowledge base, a living FAQ or a collection of operational runbooks.
At the time, it was a newsletter distributed on floppy disks or printed and physically mailed to customers.
The technology was limited.
The underlying knowledge-management model was remarkably modern.
The original support environment
There was no central system containing every customer interaction.
When someone contacted the company, the person answering the request might write the details in a notebook or record part of the solution in a local document.
Useful knowledge existed, but it was fragmented across:
- individual memory;
- handwritten notes;
- customer correspondence;
- source-code comments;
- product manuals;
- and repeated operational experience.
The same question might be investigated several times by different people because no reliable mechanism existed for finding the earlier answer.
This created predictable problems:
- customers waited longer;
- engineers repeated diagnostic work;
- answers varied between people;
- important details were forgotten;
- and expertise remained concentrated in particular individuals.
The newsletter created a way to convert that scattered experience into shared knowledge.
Learning documentation discipline from IBM
The company operated in the context of an IBM partnership, and I had absorbed several useful principles from IBM’s approach to technical documentation.
Documentation needed structure.
A useful technical article should not merely state a command or present a correction. It should explain enough context for another person to determine whether the solution applies.
The newsletter entries therefore followed a consistent pattern:
- Describe the problem clearly.
- Explain the relevant context and assumptions.
- Provide a step-by-step resolution.
- Identify known pitfalls and side effects.
This structure made the information easier to understand, validate and reuse.
TECHNICAL ARTICLE Problem ------- What is the customer observing? Context ------- Which product, version, operating system and configuration are involved? Cause ----- What is producing the behaviour? Resolution ---------- Which steps correct or work around the problem? Validation ---------- How can the customer confirm that the result is correct? Pitfalls and side effects ------------------------- What else might be affected? Applicability ------------- When should this solution not be used?
Even today, this remains a useful starting point for operational documentation.
Starting with real customer problems
The newsletter was not built from an abstract list of topics someone imagined customers might need.
It began with actual support demand.
If several customers contacted us about the same behaviour, that was evidence that the subject deserved documentation.
If an engineer needed to explain the same procedure repeatedly, the explanation should become reusable.
If a problem was difficult to diagnose once, the evidence and reasoning should be preserved so that the next investigation did not begin from zero.
This created a direct relationship between operational reality and documentation priority.
Repeated customer issue
|
v
Investigation and resolution
|
v
Structured technical article
|
v
Distribution to customers
|
v
Less repeated investigationThe newsletter was therefore part of the support system.
It reduced demand by helping customers solve known problems and by giving support staff a consistent reference.
Context prevents dangerous copying
A technical instruction without context can be worse than no documentation.
A reader may apply a valid correction to the wrong:
- product version;
- operating system;
- database;
- deployment model;
- or customer configuration.
The procedure may then fail or create another problem.
Useful documentation should state its assumptions explicitly.
For example:
Applies to: - Product release 3.x - UNIX/XENIX deployment - Multi-user installation - Standard database layout Does not apply to: - Earlier product releases - Custom database structures - Environments already using the revised configuration
This information helps the reader decide whether to proceed or seek additional support.
The first feedback loop
The most valuable part of the process emerged after distribution.
Feedback returned slowly and unpredictably.
A customer might telephone and say:
This article solved our problem.
Another might explain:
This part was not clear, and we were unsure which option to choose.
Feedback also arrived through fax messages or conversations during customer visits.
I captured those observations and incorporated them into the next edition.
A confusing step could be rewritten. A missing assumption could be added. A newly discovered side effect could be documented. A procedure that worked particularly well could be highlighted.
The article evolved because people used it.
Capture problem
|
v
Document solution
|
v
Publish
|
v
Customer uses documentation
|
v
Feedback arrives
|
v
Correct and improve
|
+--------> Publish next editionIt was an early continuous-improvement loop for operational knowledge.
Distribution before the internet
Distribution reflected the technology available at the time.
The newsletter was delivered in two principal ways:
- electronically on floppy disks;
- or as printed material sent through the post.
By current standards, this process appears extremely slow.
There was no instant publication, search index, notification service or analytics dashboard.
Updating an article meant preparing a new edition and physically redistributing it.
Nevertheless, the newsletter was effective because it addressed a genuine need.
A technically advanced platform is not required for useful knowledge management.
The essential ingredients are:
- relevant content;
- clear structure;
- reliable distribution;
- and a way to incorporate feedback.
The tool is not the knowledge system
Modern organisations have access to sophisticated documentation platforms.
They can provide:
- full-text search;
- version history;
- access control;
- templates;
- comments;
- automated links;
- and integration with ticketing and source control.
These capabilities are useful.
They do not guarantee that the organisation has a functioning knowledge system.
A modern wiki can still contain:
- outdated instructions;
- duplicated pages;
- contradictory procedures;
- documents with no owner;
- and information nobody can find.
The platform stores documents.
The operating model turns them into useful knowledge.
Documentation needs ownership
Every operational article should have an owner.
Ownership does not mean that one person must answer every question personally.
It means someone is accountable for ensuring that the content remains:
- accurate;
- relevant;
- discoverable;
- and reviewed at an appropriate interval.
Without ownership, obsolete documentation tends to remain indefinitely because nobody feels authorised to update or remove it.
Readers then lose confidence in the complete knowledge base.
Once people assume that documentation is probably outdated, they stop consulting it and return to asking individuals directly.
The organisation recreates its dependence on personal memory.
Documentation has a lifecycle
A useful article should move through a defined lifecycle.
Identified need
|
v
Draft
|
v
Technical review
|
v
Publish
|
v
Use and feedback
|
v
Revise
|
+------> Continue while relevant
|
+------> Archive or retire when obsoleteArchiving is as important as creation.
Removing or clearly marking obsolete information prevents readers from applying an old procedure to a current system.
Connect documentation to operational work
Documentation is more likely to remain current when updating it is part of ordinary engineering activity.
Examples include:
- a resolved support ticket creates or improves an article;
- an incident review updates the relevant runbook;
- a software release updates affected procedures;
- an architectural change updates diagrams and dependencies;
- and a repeated question is converted into a reusable answer.
Documentation should not depend on someone eventually finding spare time.
If the work changes operational knowledge, maintaining that knowledge is part of completing the work.
Runbooks need validation
An operational procedure is not proven simply because it has been written.
It should be exercised.
Validation can reveal:
- missing prerequisites;
- incorrect commands;
- ambiguous decision points;
- outdated screenshots;
- insufficient permissions;
- and dependencies the author assumed were obvious.
Where practical, another person should test the instructions.
The author already knows what the document intends to say. A new reader reveals what it actually says.
Feedback should be easy
In the 1990s, feedback arrived through telephone calls, fax messages and visits.
Modern tools can make the process much easier, but only if people know how to contribute.
A knowledge page should provide a simple way to:
- report an error;
- ask for clarification;
- suggest an improvement;
- or identify an obsolete procedure.
Feedback should reach the owner and produce a visible outcome.
If people repeatedly submit corrections that disappear without response, they will stop contributing.
Measuring usefulness rather than volume
Counting pages is not a meaningful measure of documentation quality.
A large knowledge base may still fail to help users.
More useful questions include:
- Can people find the correct answer?
- Does the procedure work?
- Does it reduce repeated support effort?
- Are important operational tasks covered?
- How quickly are errors corrected?
- Which searches produce no useful result?
- Which incidents reveal missing knowledge?
The objective is not to maximise documentation output.
It is to reduce uncertainty and enable safe, repeatable action.
Documentation as part of the system
Operational documentation should be treated as a component of the service.
If a system requires a particular recovery procedure and that procedure is unavailable or incorrect, the service is less recoverable.
If only one engineer knows how to perform a critical task, the person has become an undocumented dependency.
The technical platform may contain redundancy while the operational knowledge remains a single point of failure.
Technical service
+
Operational procedure
+
Current architectural knowledge
+
People able to use both
=
Recoverable systemThe lesson that remained
Producing that newsletter was my first direct experience with operational documentation that genuinely mattered.
It was not a theoretical documentation exercise.
Every article represented a real problem encountered by a real customer.
Every correction represented feedback from someone attempting to use the information.
Every new edition improved the company’s shared ability to support its products.
The delivery mechanism now looks primitive: floppy disks and printed pages sent through the post.
The underlying principles remain valid:
- capture knowledge from real work;
- structure it clearly;
- include context and limitations;
- distribute it reliably;
- observe how people use it;
- and improve it through feedback.
Long before terms such as knowledge base, runbook, post-mortem and continuous improvement became common, we were already applying the same essential idea:
Operational experience should not disappear when a telephone call ends.
It should become knowledge the whole organisation can use.
This article is based on my original ideas, experience, analysis and conclusions. Artificial intelligence tools were subsequently used as editorial and research assistants to review grammar and wording, improve structure and presentation, organise some arguments into clearer logical sections, and help review references to legal, regulatory and technical concepts.
Where relevant, factual and regulatory references were checked against the sources cited in the article. AI assistance does not replace professional legal, regulatory, financial or technical advice, and the final selection, interpretation, opinions and conclusions presented here remain my own.
Comments
Post a Comment