The Repository Knows Why

Skip main navigation (Press Enter).

IBM Z Simplification

×

IBM Z Simplification

Transforming IBM Z into an simpler, more intuitive platform so every user, from beginners to experts, can learn faster, work confidently, and drive meaningful outcomes.

Group Home

Threads<br>11

Blogs<br>13

Upcoming Events

Library

Members<br>175

View Only

Share

Share on LinkedIn

Share on X

Share on Facebook

Back to Blog List

The Repository Knows Why

By<br>Frank De Gilio

posted<br>yesterday

Like

Documentation as Code: making z/OS knowledge durable, discoverable, and honest

Field Note — May 15, 2025, 3:00 PM — Production z/OS, PROCLIB, Sacramento, California — PROCLIB member update

A started task proc has a symbolic parameter set to a value that differs from every other proc in the library. No ticket references it. The inline comment says "DO NOT CHANGE." The sysprog who wrote that comment left the company in 2017. No one currently on the team knows what happens if it is changed, so no one changes it.

The knowledge that lives in people

Every z/OS installation carries a body of knowledge that does not live in any document. It lives in people. The sysprog who remembers why that PARMLIB member was structured that way. The operator who knows which started task occasionally needs a manual kick. The security administrator who can tell you, from memory, which ESM profile was the exception and why the exception was made. This knowledge is real, it is valuable, and it is fragile.

The fragility is not a recent problem, but it has become a more urgent one. The people who hold this knowledge are retiring at a rate the industry has been tracking with concern for years. The replacements they leave behind are talented, but they arrive without the institutional context that took decades to accumulate. When a critical system behaves unexpectedly, the answer to why is increasingly not findable because the person who knew is gone and the documentation that should exist was never written.

Documentation as Code is the practice of treating documentation with the same discipline applied to everything else in this series: version-controlled, reviewed, kept alongside the systems it describes, and maintained as a living artifact rather than a snapshot that ages into irrelevance. It does not solve the retirement problem. It does make the knowledge survivable.

What documentation as code actually means

Documentation as Code is not a documentation tool. It is a discipline that changes where documentation lives, how it is maintained, and who is responsible for it.

In the traditional model, documentation lives somewhere adjacent to the system it describes: a wiki page, a SharePoint folder, a binder on a shelf, a comment block that was accurate when written in 2011. The system changes and the documentation does not, because updating documentation requires a separate act of will that routinely loses the competition for attention. Over time the documentation drifts from reality until it is either ignored or, worse, trusted when it should not be.

When documentation lives in the same repository as the configuration, code, and procedures it describes, the relationship changes. A change to a PARMLIB member travels through the same pipeline as a change to the runbook that explains that member. A reviewer who sees the configuration change also sees whether the documentation was updated. A pull request that changes behavior without explaining it can be sent back. Documentation stops being a parallel track and becomes part of the change itself.

The format is deliberately simple. Plain text files, Markdown, structured YAML comments, annotated JCL. Formats that can be read in any editor, diffed in any version control system, and searched with any tool. Not a documentation platform that requires a subscription, a license, or institutional memory of its own to operate.

PARMLIB, revisited briefly

Article 2 in this series addressed PARMLIB through the lens of Configuration as Code: consolidating members into logical YAML files organized around function rather than IBM component boundaries, with schema-aware editing catching errors at the moment of entry and automation handling the translation to dataset member syntax. That model eliminates a significant category of human error and gives the system a reviewable, attributable change history.

What it does not fully solve is the reasoning problem. A YAML file in the repository tells you what a parameter is set to and who changed it last. It does not tell you why that value was chosen over the alternatives, what was considered and rejected, or what the consequences of changing it would be. Documentation as Code is the discipline that fills that gap. The configuration record and the reasoning record belong together, and PARMLIB, which is already under version control, is the natural place to establish that pairing first.

The same principle extends across every library the system...