The usual way people start building onboarding quests: gather the onboarding pages from the wiki, pull the key sentence out of each one, and turn it into a question. What comes out is a quiz. Twenty items asking who approves a change request, which new hires answer by searching the document. They score well and still freeze the first time a real change request arrives.
Converting documents into quests is not a matter of turning sentences into questions. It is the work of finding the decision points the documents never wrote down. The five steps below change the result if you actually run them in order.
Why You Cannot Port the Wiki Straight Into Quests
An internal wiki is built to be looked up. Because it is read on demand, the order of judgment and the exception handling are usually missing. What it records is the final form of a rule. Urgent deploys go out after the team lead approves is accurate, but what to do when the team lead is on leave, and where the line for urgent sits, are not in there.
That blank is exactly where new hires get stuck. So the starting point for conversion is not the wiki. It is the questions that remain after reading the wiki.
The Five-Step Conversion Workflow
Step 1. Collect Repeated Questions
Gather the questions that actually came up over the last two or three months. The sources already exist: what new hires asked in team channels, internal chatbot logs, one-on-one notes, the answers the onboarding owner keeps repeating, and the comments that recur in code review.
Count question types, not question sentences. Who should I ask about this and who makes this decision are the same type. Once you have thirty to fifty of them, the top ten types will account for more than half the volume. Build quests only from those ten.
A collection pass looks roughly like this: how to handle an incoming change request, nine times; who to notify and in what order during an incident, seven; the go or no-go bar for an issue found before launch, six; how to push back when a requirement is vague, six; when to request a deliverable review, four.
Step 2. Extract the Decision Point
From each question type, pull exactly one point where behavior actually diverges. The test is whether choosing wrong here costs something. If nothing is lost, it belongs in a document, not a quest.
In the change-request type, for instance, the decision point is not who holds approval authority. That is a lookup. The real decision point is what happens in the minute after the request arrives: check impact first, notify the affected roles first, or tell the client when a reply is coming first.
One quest carries one decision point. Put two in and the player cannot tell why they were wrong, and the wrong-answer data becomes uninterpretable.
Step 3. Write the Situation Card
Move the decision point into a concrete situation. Situation cards have to be short; past five sentences people stop reading and skip to the options. Four elements need to be in there: the timing, the actor, the event, and one constraint.
Situation: Four days before launch, the client emails asking for a new banner area on the main page. The design is already locked and markup is in progress, and QA starts in two days. Question: As the project PMO, what do you do first?
Timing, actor, event, and constraint all sit in one paragraph. The closer the constraint is to a real project, the better. When the dates and deliverable names resemble the real ones, engagement changes noticeably.
Step 4. Design Options and Feedback
This is the step where quality separates. Most onboarding quizzes fail because the wrong answers are badly made. Nobody picks an option that says ignore the client.
Good wrong answers are half right. They have to be things a new hire would plausibly do. For the banner card above, the options can look like this.
1. Reply that the change is impossible because the design is locked. 2. Ask the publisher first whether the work is feasible. 3. Write up the request, check schedule, scope, and QA impact, then tell the client when a decision is coming. 4. Treat the banner as small work with no QA impact and ask the team to proceed immediately.
Options 2 and 4 come up constantly in real projects. Option 2 has no bad intent, only the wrong order. Option 4 handled impact by guessing. Wrong answers like these are what make the wrong-answer data worth reading.
Feedback should explain the reason rather than announce the verdict. A player who picked option 4 gets told that the QA scope added by a new banner was never checked, and that work size and QA impact are separate questions. Two or three sentences is plenty, with a link to the relevant document.
Step 5. Place by Difficulty and Role, Then Connect the Report
Now place the quests. Tune difficulty by the amount of context, not by how hard the answer is. Beginner has one constraint, intermediate has two constraints in conflict, and advanced has no single clean answer and asks the player to justify one.
For role placement, reuse the same event. That one banner request yields five quests. The PMO handles the order of operations, the planner asks the questions that make the requirement concrete, the designer weighs the conflict with the existing visual hierarchy, the publisher looks at responsive layout impact, and the developer scopes the CMS structure change. Seeing one situation through five roles is itself the lesson.
Finally, connect it to the report. Tag each quest with a judgment type and you get accuracy by type after a play session. Change management, escalation, requirement clarification, and quality bar are enough categories to start. The report serves the individual and the organization at the same time: when everyone misses the same type, the thing to fix is the document, not the people.
Common Failure Patterns
- Obvious answers. If only one of four options is long and polite, that is the answer.
- Lookup quizzes. If searching the document produces the answer, a document link does the job better than a quest.
- Cards with more than one decision point. You cannot tell what went wrong.
- Too much game. Build points, badges, and leaderboards first and they will mask a content quality problem.
- Stale answers. When the process changes and the quest does not, you are teaching new hires an obsolete procedure.
- Twenty quests in one batch. Build five, pilot them, look at where wrong answers cluster, then expand.
Conversion Checklist
- Did you count question types rather than question sentences?
- Did you build quests only from the top ten types?
- Does each quest carry exactly one decision point?
- Does each situation card have timing, actor, event, and a constraint?
- Are at least two wrong options things someone would plausibly do?
- Does the feedback explain the reason instead of the verdict?
- Is each quest tagged by judgment type so the report can aggregate it?
- Is someone responsible for updating quests when the process changes?
Wrapping Up
The core of this workflow is step one, not step three. Collect repeated questions properly and the set of quests worth building narrows on its own, and you stop writing problems about things nobody ever asked. The wiki still matters. It is just that once you know which questions it fails to answer, what onboarding needs to build becomes obvious.
---