Nehad Al Ghadri on stage, holding a microphone

Learner Guide Engine

An engine I built that turns a subject-matter expert’s course outline into a finished learner guide deck on the client’s own template, word for word.

Outline to finished guide
~2h
Client lines kept word for word
190/190
Guides live on the client site
10

Python, python-pptx, python-docx, PyMuPDF, PowerPoint, LibreOffice

A learner guide starts as an outline that a subject-matter expert writes in Word. Somebody then lays it out on the client’s template, page by page. The rule on this project was that the expert’s words are the content and nobody downstream changes them, even to fix a typo or to make a sentence fit its box. I built the Learner Guide Engine to do the layout and leave every word alone.

What I built

One outline goes in and one guide comes out, and the engine writes no sentence of its own.

The plan comes first
The engine reads the outline, maps it onto the nine parts of a guide and names a shape for every page. That plan goes in front of the instructional designer, and nothing is built before their yes.
It reads structure
The engine picks a diagram from how the expert laid the lines out: a lead with its children, a run of “Label: meaning” lines, a list of steps. A word like “Procedure” never triggers one. Lines that no rule covers are set as plain text and listed in the plan, which keeps a wrong diagram off the page.
Nothing is cut and nothing shrinks
A long outline makes a long guide, and overflow continues on a page of the same shape. A part the outline leaves empty keeps its page and shows a grey “Content needed” box.
The check can fail
After the build, a check proves that every string on every page is the outline’s, character for character, typos included. The check also plants a sentence that should not be there and has to catch it. Then the engine renders the pages through real PowerPoint, and I read them before anyone else does.
It learns how guides are shown
The engine never learns wording. What it learns is how the reviewers like guides shown: a shape they turn off, a size they keep changing. A preference binds when a reviewer says it, or when it shows up on two different guides.

Why an engine and a pack

I built the first version in a day for one client’s template, and it passed on the two outlines it was tuned on. A full read of the code then found 22 bugs, every one of them on outlines shaped differently from those two. That is why I split it in three. The engine holds no client word. A client pack carries the template and its fixed sentences. A sample pack, with a plain template and three made-up outlines, lets the tests (more than 350 of them) and a colleague’s copy run with nothing of the client’s inside.

What it delivers

A guide now takes about one and a half to two hours from the expert’s outline to my save. On one guide, all 190 lines traced back to the client’s source character for character, with no line of mine in the body. Ten guides are live on the client’s site. When the structure of the guides changed, all ten followed in a morning.

What is left is the look of the pages. Every correction I give on a guide becomes a rule in the engine the same day, and the aim I hold it to is that each new guide needs fewer of my changes than the last.

All work