Skip to content

Articles and Lessons

An answer is what your organization says, stated once for everyone. An Article is that truth explained for one group of people, and a Lesson is how they come to know it rather than merely consult it.

So an article is not a general-purpose document. It is a much narrower thing:

One article answers one question, for one readership.

Everything on this page follows from that sentence.

Two artifacts, two jobs

Every article Mention writes gets a lesson composed from it. They cover the same material and do different jobs.

Article Lesson
Shape One markdown document A sequence of 5 to 9 exercises
Job Consult what you already know Come to know it
Written from Your organization's facts, plus any answer already on record The Article, plus situations drawn from your sources
What it produces A document to read Graded attempts, per piece of material

The short version: the Article is what you consult; the Lesson is what makes you know it.

An Article is the right shape for looking something up. It is the wrong shape for learning something for the first time. Nobody learns a procedure by reading eight paragraphs about it, and a member who has read an Article and a member who has not are indistinguishable to everyone, including themselves.

So the Article stays exactly as it was, and a Lesson is composed from it.

An article answers a question

There is no taxonomy of document types to learn, and no fixed set of documents a subject must have. An article usually exists because there was a question worth explaining at length, and where that is true it says so — the page reads Written to answer "…", quoting the question in the words it was asked in.

Questions reach an article two ways:

  • Mention proposes one. When it fills an audience's contents, it works from what that audience has actually asked and from the topics your sources talk about, and a proposed entry names the question it is there to answer when one claimed the subject.
  • An owner promotes one. An answered question is sometimes worth more than an archive entry, so the owner turns it into a lesson. The recorded answer becomes the brief and the article is written from your knowledge base around it. See Turning a question into a lesson.

Either way you steer the article through its prompt, which is a brief rather than a draft: describe what the document must cover and let Mention pull the facts. See Curating Contents.

A document that answers two questions at once answers neither well. A set of instructions that stops to explain its own history loses the reader mid-task; a description of how something works that starts telling you what to do cannot be scanned for a single fact. Keeping one article to one question is what keeps both readable.

Topics group the pairs

Every article can be filed under a topic — the glossary term it explains — and the topic is how a reader finds it. A topic holds however many Article–Lesson pairs it has been given: there is no ceiling, no target, and no grid of slots to fill. If a subject deserves six lessons, it gets six; if it deserves one, one is not a shortfall.

The same topic can be explained several times over for several different readerships. Support and Sales need the same truth in different words; the facts are what they share, and the articles are what differ.

Mention will not propose two entries under the same title for one audience, which is what stops obvious duplication on a later run. Beyond that, whether two lessons cover similar ground is the owner's judgement — nothing blocks you, and a duplicate is yours to remove.

Not everything an audience reads is anchored to a topic. An article no topic claims works exactly like the rest — it just sits under General, which is where anything unfiled lives. General comes last, appears only when something is in it, and is not a topic in its own right: it has no brief and cannot be removed. See Curating Contents.

How a Lesson is made

Once Mention finishes writing an Article, it composes that Article's Lesson automatically. One Article, one Lesson — there is nothing to commission separately and nothing extra for an owner to write.

The Lesson is authored from the Article rather than parsed out of it: Mention reads the finished document and writes exercises against what it says. Two rules govern where the material comes from.

  • The Article is the only authority on what is correct. Every answer key and every rubric criterion is justified against it, so a Lesson can never grade you against something the Article does not say.
  • Your sources supply the situations. Realistic scenarios and plausible-but-flawed artifacts come from your organization's own material, fictionalized — names and identifying details are replaced, because a Lesson is shown to a whole Audience.

When the Article is rewritten — a changed prompt, shifted source material, an owner settling an answer the article rests on — its Lesson is composed again from the updated document. Each rewrite is also recorded in the Article's change history — a dated summary of what changed — shown on the article and collected on the Lessons page under Recently changed.

Not every article affords a Lesson. Some material is genuinely inert — a page of links, a list of names with nothing that turns on them — and Mention says so rather than padding a lesson out; the entry keeps its Article and its Lesson shows as No lesson possible with the reason. That is a verdict, not an error — a Lesson only shows as failed when something actually went wrong composing it. Describing how something works rather than how to do it is not what makes an entry inert: a description is exercised by applying its facts, not by reciting them. See Curating Lessons.

What an exercise is

Every exercise has the same three parts: a setup (a situation or a question), the learner's attempt, and then the correction. Nothing is revealed before the learner commits, which means there is nowhere in a Lesson to put an explanation except after an attempt.

Exercises come in six kinds — a warm-up guess before being taught, deciding in a messy scenario, telling near-identical cases apart, critiquing a flawed artifact, reconstructing a procedure from memory, and explaining why a rule exists. They are graded two ways: picking from options, checked against an answer key, or writing prose, judged against a rubric of criteria. Passing a written answer means meeting every required criterion. The warm-up is never graded. See Working Through Lessons for what this feels like from the learner's side.

Roleplay is not a Lesson exercise but the Audience's final exam: one multi-turn conversation drawn across every Lesson once a learner has finished them all, sampling the material they hold most weakly and graded once at the end. A topic that falls down there drops back to the first review rung and falls due immediately. See Tracking Your Progress.

Which of the six a Lesson uses follows from what its Article actually says. An exercise has to be answerable from the document it was composed from: an article with no procedure in it gets no reconstruction exercise, and one that states no reason gets nothing to explain. Every Lesson opens with the warm-up guess.

This is also why review can bring material back as a different exercise than the one that taught it, but never as one the Article cannot settle.

Learn mode and Read mode

Which artifact an entry opens is derived from the member's progress, not chosen by anyone.

Mode Condition What the entry opens
Learn The Lesson isn't finished yet The Lesson, one exercise at a time
Read The Lesson is finished The Article in full

Neither mode withholds the Article. It is reference material a member may need before, during, or long after its Lesson, so it stays readable by its own link and read_article always returns the whole document. What the mode decides is which half the entry is asking for.

A Lesson is open book; review is closed book. Every exercise carries the passage of the Article it was composed from, and a learner may open it before answering at no cost — finding the right material and applying it is a competency, and it is the one a first pass practises. Whether the material stuck without the document is what review checks, so a review item carries no such passage.

This applies identically in the web app and through the MCP server. Modes describe what a learner is served. An Audience's owners are not learners in it, so they are not in either mode: they read every article they commissioned from the entry's page in Learn, regardless of progress, because they have none.

Mastery attaches to material, not to exercises

Every exercise declares the piece of material it exercises — "the 48-hour threshold for legal escalation" — and a learner's mastery is recorded against that, not against the exercise.

This is the choice that makes the rest work:

  • It survives a rewrite. Rebuilding a Lesson after its Article changed keeps everyone's progress on the material that didn't change.
  • It survives an edit. An owner swapping a recall exercise for a scenario over the same material resets nobody.
  • It is the right key for review. What comes back is material you are shaky on, in whatever form suits it that day.

A learner has completed a Lesson when they have passed every piece of material it grades. Completion is taken back in exactly one case: a rewrite whose recomposed Lesson grades material the learner has never been asked about. Everything they already passed stays passed, and the entry asks them for the rest. Coverage that a rewrite removes never costs anyone their completion.

Review, and what "current" means

Completion is not the end state. A Lesson finished once and never revisited produces someone who knew something in March.

Mastered material returns on a fixed ladder — 1 day, 3 days, 7 days, 21 days, 60 days. Passing moves the learner up a rung; failing resets them to the first. Because mastery is keyed to material rather than to exercises, a review item can come back as a different kind of exercise than the one that first taught it.

That gives two different statements about a learner and an Audience, and they mean different things:

  • Complete — they have finished every Lesson in the Audience.
  • Current — they have finished every Lesson and nothing in the Audience is overdue.

Current is the honest number, and it is the first straight answer this product has been able to give to "does my team know this." It also means an Audience that is complete can stop being current. See Monitoring Progress.