The admin who knew the grading rules left in May
A school we work with had a report card module that produced correct results for two years. Then the vice principal who configured the grade boundaries, subject weights, and rounding rules took a post at another school in May. The new academic year started in July, and nobody could reproduce the configuration. The module was technically running, but nobody trusted its output.
The problem was not a missing feature. The problem was that the configuration lived in the database with no in-system record of why each value was set, what it meant, or what the alternatives were.
We rebuilt the module so that every configurable rule carries its own context. A grade boundary is not just a row in a table — it is a named, dated entry with a note from whoever set it.
Configuration that explains itself
The grading configuration screen now looks like this for each entry:
Grade boundary: A1
Min percentage: 91
Max percentage: 100
Set by: Priya Sharma (Vice Principal)
Set on: 2024-04-12
Note: CBSE 2024-25 scheme. Previous year used 90-100.When the new vice principal opens the screen, she sees not just what the values are but who chose them, when, and against which board guideline. She can change them, but she does not have to guess what the previous person intended.
This adds two columns to the config table — `set_by` and `set_on` — and a `note` text field. It is not clever architecture. It is a discipline we apply to every configurable surface in the system.
Naming workflows in plain language
The same school had approval workflows for fee concessions. The previous admin had set up five workflows named things like "WF_CAT1" and "WF_MGMT_REL." Nobody remembered what CAT1 meant. The concession types themselves were clear — sibling discount, staff ward, management quota — but the workflow names were shorthand that only one person used.
We renamed them to match the concession type and added a description field that shows on the workflow editor screen. "Sibling discount — application to accounts to principal" is longer than "WF_CAT1," but a new admin can read it and understand the chain without asking anyone.
Where we do not automate documentation
We considered generating documentation automatically from the schema — a data dictionary, a workflow diagram, a config export. We decided against it for two reasons.
First, auto-generated documentation describes structure, not intent. It tells you that a `grade_boundary` table exists with columns `min_pct` and `max_pct`. It does not tell you that the 91 lower bound comes from the CBSE 2024-25 circular. The note field, written by the person doing the configuration, carries intent.
Second, generated docs rot. They get produced once, saved as a PDF, and forgotten. In-system context stays where the configuration happens. When someone changes a grade boundary, the note field is right there on the same screen.
The tradeoff: slower configuration
This approach makes initial setup slower. The person configuring the system has to write a note for every rule they set. For a school with 12 subjects, 8 grade boundaries, and 6 concession workflows, that is roughly 30 notes to write during setup.
We think that cost is worth it. The alternative is a system that works perfectly for two years and then becomes unreadable when one person leaves. Schools in particular have high administrative turnover — principals serve three-to-five-year terms, vice principals rotate, and clerical staff changes annually. A system that depends on one person's memory is a system with a deadline.
What we ship
Every ERP we build now has three things on every configuration screen: who set the value, when they set it, and a free-text note. The note is required, not optional. If someone cannot write a sentence explaining why they chose a value, the value is probably wrong.