Self-Explaining Reports: Every EDGEBIC Column Defines Itself

Every report column in EDGEBIC by User Solutions carries its own documentation inside the product: click Column Details in any report window and each column explains what it means, how it is computed, what unit it is in, and what a good, a nominal, and a bad value look like. No separate manual, no tribal knowledge, no spreadsheet of definitions that went stale two versions ago. This post covers what the system is, why it was built this way, and what it changes for a plant where more than one person reads a number.

The reports themselves are cataloged in the report overview; the click-by-click version of the dialog is in how to use Column Details.

The Problem It Solves

Scheduling software is dense with acronyms: SPI, CPI, EAC, VAC, OEE, adherence, attainment, backlog, availability. Each one has a precise definition and a specific trap. Percent complete is capped at 100. SPI defaults to 1.00 when nothing was planned yet. Availability is measured against configured shift hours, not against the calendar. None of that is complicated, and all of it is forgettable.

The usual answer is a training document. Documents have two failure modes: nobody has them open at the moment they read the number, and they drift the first time a formula changes. So the definitions in EDGEBIC live where the number lives, and they are structured data rather than prose, which is what keeps them attached to the column they describe.

What You Actually See

Click Column Details in the footer of a report window and a two-pane dialog opens. The left list is every documented column of that report, in display order. The right pane shows the selected column, with as many of these as apply:

The dialog opens with the first column already selected, so the right pane is populated before you click anything.

A Real Entry, End to End

Take SPI on the earned value report, because it is the entry most planners meet first.

Full name: Schedule Performance Index. Description: whether the job is ahead or behind schedule. 1.0 means exactly on plan. Below 1.0 means behind, having earned less credit than the plan expected by now. Above 1.0 means ahead. It is a productivity-of-time measure and says nothing about cost. Formula: earned value divided by planned value. Unit: ratio. Examples:

See also: planned value hours, earned value hours, CPI.

That last line is the part people underestimate. A planner reading about SPI is pointed straight at CPI, which is the number that tells them whether the job is also over budget. The two together produce the correct action; either alone produces half of it. The on-time reports deep dive works a job where SPI reads 1.09 and CPI reads 0.91 at the same time, which is exactly the case the see-also link exists to catch.

The Examples Are the Point

Three examples per non-trivial column: one nominal, one good case, one bad case. That pattern is deliberate, and it is what makes the dialog useful in the two seconds a planner actually has.

Definitions tell you what a number is. Examples tell you whether yours is bad. A ratio column showing 0.82 means nothing to most readers until they see "over budget: every hour worked earns only 0.82 hours of credit" next to it. An on-hand quantity of minus 30 looks like corruption until the entry shows "-30: over-issued, 30 units consumed before the matching receipt landed" and the reader realises it is a documented state rather than a fault.

The same design runs through the diagnostic reports. On the setup matrix columns, the entry for where a changeover time came from lists real codes with real meanings: a cold start used the routing default because nothing ran on that machine before, a family match used a light-to-dark changeover cell, a product match used a specific pair override. A planner who reads "family matrix, white to black, 240 minutes" now knows precisely which cell of which matrix to edit.

Two Audiences, One Source

The glossary was built to serve people and software from the same records. Each entry stores its definition, formula, unit, examples, related terms, and source as separate fields rather than as a paragraph, and the whole service is independent of the desktop interface. That means the identical content can drive the in-app dialog today and structured lookups elsewhere later, without a second copy to maintain.

Why that matters even if you never touch an interface other than the dialog: a documentation system with one source cannot disagree with itself. The tooltip, the dialog, and anything built on it later all read the same record. The alternative (a definition in a manual, a different one in a tooltip, a third in a training deck) is how three people end up reading one report three ways.

What Is Covered Today

Twenty-one report glossaries ship, and between them they document the reports a planner uses daily:

Reports without a registered glossary hide the button rather than opening an empty dialog, which is worth knowing so a missing button reads as "not documented yet" rather than "broken".

The optimizer entry deserves a specific mention, because it documents terms that are otherwise genuinely hard to explain in a hallway: the goals and presets the optimizer works to, and the certificate terms it reports back, including what an optimality gap is and what "never worse than the baseline" guarantees. Those are exactly the words a planner needs defined before trusting a proposal, and they live one click from the proposal.

What It Changes in Practice

New planners get productive faster. A person who joins your plant on Monday does not need to learn the acronym set before reading a report; they need to know that the definition is one click away. That is a much smaller thing to learn.

Arguments become shorter. Most disputes about a report are definitional rather than factual. When the definition is on the screen with three worked examples, the argument resolves in seconds and moves to the thing that actually matters.

Audits get an artefact. Quality systems ask where numbers come from. Each entry carries a source field naming exactly where the value is computed, so the answer is a screen rather than a recollection. Combined with an exported PDF of the report at decision time, that is a defensible record.

Documentation stops drifting. The definitions live with the code that produces the numbers rather than in a parallel document, and the links between related columns are validated automatically, so a typo in a see-also reference cannot ship as a dead end. The engineering discipline behind that is the subject of why every column carries its own definition.

Cross-team numbers stop needing a translator. Finance reads hours, the floor reads pieces, sales reads dates, and each of those groups meets the same report from a different direction. When the unit is stated on the entry (hours, pieces, percent, ratio, currency, date, flag) and the formula names its own denominator, a conversation between two of those groups starts from an agreed quantity rather than from a definition negotiation. That is worth more in a monthly review than any additional column.

Build the Habit Early

The single cheapest quality improvement available in the reporting layer is a rule: click Column Details before quoting a number you have not quoted before. Most of the classic misreadings, collected in report reading mistakes and report terminology mistakes, are one click from being impossible, because the entry for percent complete says it is capped and the entry for SPI says what an SPI of 1.00 means on a job that has not started.

For the metric concepts behind the acronyms, our manufacturing KPI guide is the generic reference, and the definitions themselves follow the vocabulary shared across the APICS and ASCM body of knowledge. For the system that produces the numbers, start at the complete EDGEBIC guide.

Want to see your own metrics with their definitions attached? Bring a report you argue about to a demo and we will open the entry for every column on it.