Authoring rules

A course is written by many hands over a long time: lecturers, teaching assistants, and AI assistants. Rules settle the decisions that should not be argued again in every lesson: how a symbol is written, which kind of chart a figure uses, how long a heading may be, which word names a concept. Readers get a course that uses one term per concept and one meaning per symbol from the first chapter to the last. Authors and their assistants spend less time on review, because many decisions are already made and the build checks many of them.

What the rules cover

About forty rules ship with explico, in five areas:

Area	Covers	Example rule
N Notation	how math symbols are written and explained	One meaning per symbol, defined once
V Visualizations	diagrams, charts, interactive figures	Every quantitative axis shows at least three labelled values
S Structure	headings, part pages, tables, conventions	No heading longer than 65 characters
P Prose	how sentences and terms are worded	One term for each concept, with no synonyms for variety
C Versioning	the course's knowledge version and changelog	Every content change lands with a changelog entry

A sixth area, X, belongs to the course itself (see Add rules of your own).

Levels of enforcement

Every rule states how it is enforced, so an author knows which rules the build will catch and which ones depend on the writer and the reviewer.

Level	What it means
Locked	The page cannot render correctly without it. Always on, and it cannot be waived. Example: every symbol in an equation must have a definition.
Script	A check runs on every build and reports each break with its file and line.
Partial	A check covers the part a script can see, and a reviewer covers the rest.
Guide	No script can judge it, for example whether a sentence states one claim. The rule tells the writer and the reviewer what to do.

A checked rule reports at one of three severities. An error stops the build, because the content is wrong, ambiguous, or would not render. A warning does not stop the build but marks something to repair. An info finding is advice that can be left as it is.

The rules in effect

Each course gets one generated page that lists only the rules switched on for it. The page groups them by what they are about (prose, math, tables, plots, and so on) and gives each one its enforcement level and its current settings. It fits in about a hundred lines.

That page is what an AI assistant reads before it drafts a lesson. It learns the rules of this course, not of every course, so it neither applies nor flags a rule the course has turned off.

Tune them in a form

All course settings live in one settings file, and the rules are part of it. In VS Code, the explico settings editor opens that file as a form, with a title and help text on every field:

• switch a rule off for this course;
• tune a rule's settings, such as the longest allowed heading, or the abbreviations the course treats as known;
• see a problem inline when a field is required or malformed.

The form writes an ordinary settings file, so the change shows up as a normal diff for review. Locked rules cannot be switched off.

Add rules of your own

A course often has a house style that no engine could ship: a phrase this cohort must not see, a paragraph shape a department agreed on, a convention that holds for one subject only. Such rules go in the same settings file, edited in the same form, numbered X1 to X99.

• Enforced or guide, from one field. Give a rule a text pattern and the build reports every match, at the severity you chose. Leave the pattern out and the rule is a guide, listed for the writer and the reviewer like any other.
• Park a rule for later. A rule switched off stays in the file with its text, so next term's rules can wait without affecting this term's lessons.
• Safe across upgrades. explico never ships an X rule, so a course's own rules never collide with a new engine version.

Exceptions, with a reason

A rule is a strong recommendation, not a ban on judgement. When a passage must break one, the author writes a one-line comment above it that names the rule and gives the reason. The reason is mandatory and stays in the source, next to the passage it excuses. For a checked rule the comment silences the finding at that one place, and a comment that no longer silences anything is reported so it gets removed. Locked rules cannot be waived.

The full text

Every rule has a page of its own with its reasoning and examples. They ship with the npm package, under docs/authoring/, so an assistant working on a course reads the rules of exactly the explico version the course uses.

Back to explico