Teach with Torus: Start Here

A short, guided setup checklist for instructors teaching with an OLI Torus course. It asks three to five questions about the instructor's situation, then builds them a personalized, ordered checklist — with links to the exact Help Desk articles they need at each step, and a clear mark on every step saying whether they can do it themselves or need OLI's help.

It exists because the Knowledge Base documents individual tasks well but has no orienting layer: nothing tells a new instructor what order to do things in, or warns them about the one choice they cannot undo.

Built by: Sarah Lim, OLI Intern, Summer 2026 Content reviewed by: OLI Customer Support

---

Contents

• Try it
• What it does
• Embedding it in a page
• Sending an instructor straight to their own checklist
• Editing the content and links
• The files
• If something looks wrong
• What has been tested
• Known open questions

---

Try it

Download or clone this folder and open index.html in any browser. That's the whole setup — there is no server to run, nothing to install, and no build step.

You can also put the folder on any web host and link to index.html.

---

What it does

The instructor answers at most four questions:

1. Where are you in the process? — exploring, setting up, or returning
2. How will students access the course? — through your LMS, or directly on the OLI Torus website
3. Which LMS? — Canvas, Blackboard, Brightspace, or Moodle
4. Is Torus already available in your LMS? / Do you have instructor access?

Nobody is asked the same thing twice. Where an instructor might not know the answer, the way to find out opens on the question itself rather than on a screen of its own — question 2 explains the two delivery modes, and question 4 carries a two-step "how to check" and an email to OLI.

From those answers it produces one of seven checklists. The six setup checklists all end with the same shared stages — configure the course, go live, and what to watch in the first few weeks — so the advice stays consistent no matter which path someone took. The seventh is for someone still deciding: it stops after reviewing the materials, and sends them back to the questions when they are ready to set up.

There is a drawing of all of this in docs/ — every route, side by side, with the number of steps each one ends on.

Because six of the seven share the heading "Your Setup Checklist", each one carries a line underneath saying plainly whose checklist it is — the delivery mode, and the one condition that tells it apart from its neighbours. That line is written per checklist rather than assembled from the instructor's answers, so it is still there for someone who arrived from a shared link or the overview map and never answered a question.

Two things the guide is deliberately firm about:

• The delivery choice cannot be undone. A course set up for LMS delivery can never be switched to website delivery, or the reverse. The guide warns about this before the instructor chooses, and again on the overview map.
• Every step says who does it. Steps are marked either "You can do this" or "OLI will help", always with the words spelled out and never with colour alone.

There is also a "See the whole process" overview map for instructors who would rather read everything at once than answer questions. It is offered on the welcome screen, from the toolbar on every other screen, and at #overview. Consulting it costs nothing: Back returns you to the checklist or question you left, with your answers intact. There is also a "Print or save this checklist" button that produces a clean paper checklist with a tick box beside each step and every article's web address spelled out.

The overview map can be acted on, not just read. Each of its three paths ends with a button naming what that path sets up — "Preview a course", "Set up an LMS-delivered course", "Set up a website-delivered course". Two of the three ask a question or two first, because those paths lead to more than one checklist and the guide will not guess on your behalf. Back from those questions returns to the map.

The map is laid out to show its own shape: an instructor is in one of three paths, and everybody ends up in the same place afterwards, whichever one they took. The three sit together, side by side once there is room. An arrow runs from them into the block everyone reaches — tinted, spanning the full width, and set apart so it cannot be read as a fourth path to choose between.

That used to rest on the grid alone, and the grid collapses on a narrow screen: below 768px the map was four identical stacked cards with only the words "If" and "Once" to tell a path from a destination. The arrow and the tint both survive the stacked layout, so the narrow view now says the same thing the wide one does.

The arrow carries no words. It is drawn in the stylesheet and hidden from screen readers, which lose nothing: read in order, the three paths come first and the block everyone reaches comes last, and the map's intro says in words that there are three paths. That intro is now the only place the convergence is stated in words, so it should stay.

The map's three paths carry no email buttons. A path describes what it involves, so an email on one of its lines would presume the reader needs it when they may not — an instructor may already have instructor access. The email drafts live on the checklist steps instead, where the guide already knows the situation.

Above the paths, between the intro and the warning, sits one information callout about OLI Payment Codes: the same component as the warning below it, in the accent colour and without the word "Important", because it offers something rather than cautioning against something. It does carry an email, since asking is the whole point of it.

The welcome screen offers the same two ways in as equal choices, side by side and the same size: answer the questions, or read the map first. Each carries a line saying what that route does. Above them sits the full OLI Torus logo, symbol and wordmark together — this is the one screen with room to read the wordmark, and the one screen where the small header strip is hidden.

Every other screen carries the torus on its own in that header strip, beside the guide's name. The full lockup is over four times as wide as it is tall, so at header height its wordmark would be a few pixels high; the symbol alone fits. Both are crops of the single official file, bundled in img/ so the guide still asks for nothing outside its own folder.

Every screen's footer carries the support address, and clicking it opens a message already prompting for the instructor's institution — the thing OLI always has to ask for. The subject is left blank on purpose, since someone writing in from the footer could be asking about anything.

Beside that line, at the right-hand end, sits Home — the way back to the welcome screen from anywhere in the guide. It forgets the answers, exactly as "Start over" does, and it is not offered on the welcome screen itself, since that is where it goes. On a narrow screen the footer wraps and Home drops onto its own line, still at the right. It does not print.

The toolbar holds up to three controls. Back steps one question backwards and keeps everything answered before it. See the whole process opens the map from wherever you are. Start over forgets the answers and asks the first question again — it restarts the questions, not the guide, and it only appears once there is something to forget. On the map, Back returns you to the checklist you left, or to the welcome screen if you arrived there cold.

---

Embedding it in a page

Put this wherever you want the guide to appear:

<iframe
  src="https://YOUR-HOST/teach-with-torus-start-here/index.html"
  title="Teach with Torus: Start Here"
  style="width: 100%; height: 700px; border: 1px solid #d9dde2;"
  loading="lazy">
</iframe>

Notes:

• Give it a title. Screen readers announce it, and an unlabelled frame is an accessibility failure.
• Height. The checklists are long, so the guide scrolls inside the frame. 700px is comfortable; more is better if you have the room. The guide cannot resize its own frame — that would need code on the hosting page.
• Width. Any width works, down to about 320px. It reflows for phones.
• Using the guide will not disturb the Back button on the page that embeds it. This was a deliberate choice and is covered by a test.

embed-test.html in this folder is a bare page with the guide embedded, for checking how it behaves in a frame. It is not part of the guide itself and you do not need to publish it.

---

Sending an instructor straight to their own checklist

Every checklist has its own web address, so Help Desk staff can skip the questions and send someone directly to the steps that apply to them. Add the #... part to the end of the guide's address:

Add this	Where it lands
#evaluation	Getting an evaluation copy before committing
#lms-yes-canvas	LMS delivery, institution already set up (Canvas)
#lms-no-canvas	LMS delivery, institution not yet set up (Canvas)
#lms-again-canvas	Returning instructor, new LMS section (Canvas)
#direct-yes	Website delivery, already has instructor access
#direct-no	Website delivery, needs instructor access
#direct-again	Returning instructor, new website-delivery section
#overview	The whole-process overview map

Swap canvas for blackboard, brightspace, or moodle as needed. For example:

https://YOUR-HOST/teach-with-torus-start-here/index.html#lms-no-moodle

If you leave the LMS off an LMS link (just #lms-yes), the guide asks which LMS first and then shows the checklist. If a link is mistyped, the guide opens at the welcome screen instead of showing an error.

Instructors can also get their own link from the "Copy link to this checklist" button at the bottom of any checklist.

---

Editing the content and links

Everything an instructor reads lives in js/pathway.js. That is the only file you need to open to change wording, add a step, or fix a link. It is plain text with comments explaining each part, and it is organized so the things most likely to change are easiest to find.

You do not need any developer tools. Open the file in any text editor, make the change, save, and reload the page in your browser.

What is safe to edit, and what is not

The guide has words and it has wiring. The words are meant to be rewritten. The wiring decides the order of the questions and which checklist someone lands on, and changing it changes the pathway itself.

Safe — the words. Anything an instructor reads: question, label, subtext, warning, title, body, note, situation, audience, the sequences lists, and the mailto drafts. Rewrite these freely.

Leave alone — the wiring.

• id, on any question, option, or step
• next, on any option, including the by / map branching
• goTo, on any lane in the overview map
• shared, which marks the one block on the map that every path leads into rather than a path you can choose
• footerMailto in meta — the name of the draft behind the footer address
• deepLink values (see the shareable-address note below)
• the name on the left of any entry in links, mailto, or stages
• the stages list inside each entry in results

The two sit side by side in the same block, so what matters is the line, not the file:

{
  id: "exploring",                              // wiring — leave alone
  label: "I'm still exploring Torus course materials",  // words — edit freely
  next: "result:evaluation"                     // wiring — leave alone
}

The email drafts behave the same way. In each mailto entry, the label (the button text), subject, and body are all just words. The name on the left is wiring, because steps call the draft by that name:

evaluationCopy: {                                        // wiring
  label: "Email OLI to request an evaluation copy",      // words
  subject: "Torus Evaluation Copy Request",              // words
  body: "Institution:\nCourse:\n"
}

The address is not in the draft. Every button sends to meta.supportEmail at the top of the file, currently oli-help@cmu.edu. No mailto entry names an address, so rewording one cannot misdirect an instructor's email, and changing where they all go is a single edit in one place.

The subjects and bodies are deliberately plain — and this is the easiest worthwhile improvement left. Each body prompts for a few basics, such as institution, course, and account, because there was no way to know what OLI actually needs on a first approach without guessing, and a wrong guess would have instructors filling in fields nobody reads. They are a starting point rather than a considered form.

If OLI knows the three or four things that would let Support answer a request without a round of follow-up questions, putting those in the body is a genuinely small change with an immediate payoff: a few lines in this one file, nothing else to touch, and every instructor on that path sends a more useful first email. The same goes for the subject if a particular wording helps Support sort or route requests.

To change the logo

The two files are in img/, and meta.logo in js/pathway.js names them. The simplest swap is to replace the files and keep the names.

Both are crops of one official PNG from OLI. oli-torus-lockup.png is the symbol and wordmark together, shown at 280px wide, so it is bundled at 560px to stay sharp on a high-resolution screen. oli-torus-symbol.png is the torus alone, shown 28px tall in the header. The white background was keyed out, so both have transparent backgrounds and will sit on any colour.

If a vector version ever turns up, it is worth switching: these are raster images and will soften if displayed much larger than the sizes above.

The look — css/styles.css. Spacing runs on a scale — seven steps, --s1 to --s7, on a 4px rhythm. Every gap in the file uses one of them. If you need a gap, take the nearest step rather than adding an eighth: the file previously held 24 different values, several under 2px apart, and differences that small read as sloppiness rather than intent.

The typeface is set at the top of that file, and two are bundled: Open Sans, which OLI Torus uses and which is what the guide currently uses, and Lato, which the Help Desk uses. Switching is one word on the --font line — but read the note above it first, because Lato only comes in fixed weights and three of the weights this guide uses would be rounded off.

One more thing worth knowing before you change widths: the overview map is deliberately wider than the rest of the guide (body.is-overview .page). The checklists are capped for comfortable reading; the map is short labels in cards, and it needs the room to stand the three paths side by side. Narrowing the general width will not squash it.

Otherwise, colour, spacing, and type are all safe to change — CSS cannot affect the order of the guide. Restyle a class as much as you like, but do not rename one — the tests select classes such as .screen__title, .step__title, and .option__label by name.

The screen layout — js/app.js. This draws the screens and contains no wording at all. Changing it is a developer job, and it is the one file where a mistake can alter the flow without any wording appearing to change.

After an edit, check it

Takes seconds, and needs no server:

cd verification && node tests/validate.js ../js/pathway.js

It reads the config and reports any name that no longer resolves, a duplicated shareable address, or a checklist that can no longer be reached from the first question. Rewording never upsets it.

Before committing, run the full suite (node tests/test-flow.js, 352 checks). Note that it pins a few exact phrases: two question headings ("Where are you in the process", "How will your students access"), the checklist heading "Your Setup Checklist", the guide's own name, and part of each situation line. If you deliberately reword one of those, its check will fail even though nothing is broken. Update the check to match the new wording rather than undoing the edit.

To fix an article link that has moved

Find the article in the links section near the top and change its url:

viewStudentPerformance: {
  title: "View Student Performance",
  url: "https://olihelp.zohodesk.com/portal/en/kb/articles/view-student-performance"
},

Because every step refers to articles by name rather than by address, you only fix each link in this one place, however many steps point at it.

To reword a step

Find it in the stages section and edit the title, body, or note. Use plain text. There are no HTML tags, but wrapping a phrase in double asterisks marks it for emphasis — that is how the names of things to click are picked out in the how-to lists. Everything else is taken literally.

To add a step

Copy an existing step from its opening { to its closing }, paste it into the steps list where you want it to appear, and edit the text. Give it an id that no other step in that stage uses.

The rules to keep when editing

These came out of the stakeholder interviews and the accuracy review, and the guide will read badly if they are dropped:

• Write to the instructor as "you." Warm, plain, and short.
• Say "institution," never "school." Most OLI customers are universities.
• Never show internal Torus words on screen: "Template," "Project," "Community," or "LTI." Say "the course you want," "your institution's LMS," "OLI will make it available to you."
• Keep it brief. Both Help Desk interviews landed on the same point: OLI tends to overestimate how much detail instructors want.
• Use warnings sparingly. They are for things that cannot be undone or that cause real harm. If everything is a warning, nothing is. Write only the message — the guide adds the word "Important" and a colon for you.
• Link out rather than re-explaining. Where an article already covers something, link to it. Only write the steps out in full where no article exists.

Useful things to know

• {lms} anywhere in the text is replaced with whichever LMS the instructor chose. Any sentence using it must also read correctly as "your LMS," which is what appears when we don't know their LMS yet.
• Stages are shared. Editing configure changes it on all six setup checklists at once — usually what you want. The evaluation path is the exception: it has none of the shared stages, since nothing is being set up yet.
• The deepLink values are the shareable addresses in the table above. If you rename one, links people have already saved will stop working, so leave them alone unless you mean it.
• A few Zoho web addresses genuinely do not match their article titles, because Zoho keeps the original address when an article is renamed. The ones marked slug verified in the comments were opened and confirmed to load the right article. They look wrong. They are not. Please don't "fix" them.

---

The files

index.html          the page itself — you shouldn't need to touch this
css/styles.css      how it looks
fonts/              the two bundled typefaces, and their licence
img/                the OLI Torus logo, in two crops
js/pathway.js       ALL the content: questions, steps, wording, links   ← edit this
js/app.js           the code that draws the screens — no wording in it
embed-test.html     a scratch page for testing the iframe embed (optional)
README.md           this file
verification/       the test harness and the evidence behind the testing
                    claims below (optional — not part of the guide)
docs/               the user flow diagram, as a page and as slide exports
                    (optional — not part of the guide)

The guide is the eight items above verification/. Neither verification/ nor docs/ is loaded by the guide or needed to run it. verification/ is the tooling used to check the guide, kept with the repo so the testing claims can be re-checked rather than taken on trust; it has its own README. docs/ holds the flow diagram drawn for the report and the presentation, and its own README says how to keep it current.

The split between pathway.js and app.js is the point of the whole design: Torus and the Knowledge Base will keep changing, and content should be editable by whoever knows the answers, without touching code.

---

If something looks wrong

A step or link has vanished from the guide. Almost always a mistyped name in js/pathway.js. The guide checks itself when it loads and explains exactly what it could not find. To see the message, open the guide in Chrome, press F12, and click the Console tab. You will get something like:

Teach with Torus — there are 1 problem(s) in js/pathway.js.
The guide still runs, but these parts will not appear:
  • stages.postLaunch step "P1": asks for a link named
    "viewStudentPerfromance" that is not in the links list

A mistake in one place never takes the whole guide down — the rest still works.

Nothing appears at all. Usually a missing comma or bracket after an edit. The same Console tab will point at the line. If you get stuck, the last working copy is in this repository's history.

A link opens the wrong article, or an error page. Zoho has renamed or moved the article. Find it in the links section and update its url.

---

What has been tested

Verified in Chrome with an automated test suite (352 checks) plus a separate link check and a contrast audit:

• All 11 routes through the questions reach the right checklist, and every option, Back step, and "start over" behaves.
• All 8 shareable links open the right screen; a mistyped one falls back to the welcome screen; capitals work too.
• Every action on the overview map reaches the right place, asks only the questions that change what it shows, and returns to the map on Back. No path sends anyone to a checklist based on an answer they were never asked for.
• The footer carries the support address on every screen, and clicking it drafts a message asking for the instructor's institution. Beside it sits exactly one control — Home — on every screen except the welcome screen, where it would point at the page you are already on. It stays at the right-hand end at 360px, where the footer wraps and it drops onto its own line, and it is hidden in print.
• One toolbar, at the top: the welcome screen has none, and every other screen has exactly one. Back from a map opened cold reaches the welcome screen, which is otherwise unreachable from there.
• "Start over" returns to the first question and forgets the answers, and only appears once something has been answered; Back from that first question is what reaches the welcome screen.
• On the map, every badge sits below its label — side by side, stacked, and in print — rather than inline in the wide lane and wrapped in the narrow ones.
• The OLI Torus logo appears on every screen: the full lockup on the welcome screen, the torus alone in the header everywhere else, and never both at once. Both files load from inside the folder and are confirmed to decode. The lockup carries alt text; the header mark is deliberately silent, since the guide's name sits right beside it.
• The map reads as three alternatives leading into one shared block: the three paths are grouped together, the shared block sits outside that group, comes last, is tinted differently from a path card, and has an arrow drawn between. The arrow carries no text and is hidden from screen readers, and the intro still says in words that there are three paths. Checked again at 360px, where the columns collapse and the arrow and the tint are all that carry it.
• Every checklist says whose situation it is, no two say the same thing, the line names the instructor's LMS, and it survives into the printed sheet.
• All 26 Help Desk links were opened in a real browser and confirmed to load the article they claim to. Zoho serves the same page for a missing article as for a real one, so a deliberately invalid address was included as a control to prove the check actually detects a broken link.
• The guide links 26 of the 32 published instructor and LMS-administrator articles. The rest were left out on purpose: they cover ground past first setup (advanced assessment settings, per-question roster analysis) and the brevity rule matters more than completeness here. See Known open questions for the ones still worth a decision.
• Nothing is requested from outside this folder, so it works offline and inside a locked-down page. No analytics, and nothing from Google Fonts — the typeface ships in fonts/ and the OLI Torus logo in img/, and both are loaded from there. A test confirms every image comes from inside the folder and actually decodes, rather than leaving that on trust.
• The guide is set in Open Sans, the same typeface OLI Torus uses. Lato, which the Help Desk uses, is bundled as an alternative and costs nothing until it is chosen: only the typeface in use is ever downloaded.
• No sideways scrolling at 320, 360, 414, 600, 768, 1024, or 1440 pixels wide, and every button is at least 40px tall for touch.
• Print view: buttons hidden, a tick box beside each step, every article address spelled out, warnings still legible without colour.
• Embedded in an iframe: renders correctly, and clicking through does not change the hosting page's address or its Back button.
• Opened straight from disk (file://) with no server.
• Keyboard: options are real buttons, focus moves to each new screen's heading, there is a skip link, and screen-reader announcements are made on every move.
• Every one of 35 text-and-background combinations meets WCAG AA contrast, in both the normal and high-contrast colour schemes.

Not yet tested: Safari and Firefox specifically, and a real screen reader (VoiceOver or NVDA). The guide uses nothing browser-specific, but a pass in each would be worth doing.

---

Known open questions

Carried over from the content review, none of which block using the guide:

• OLI Payment Codes. The overview map says OLI can work with your campus bookstore and gives you a way to ask. That is deliberately all it says: the process is documented nowhere, and the Help Desk could not describe it when this was written. If it becomes clear, this is the one topic in the guide where the wording is a placeholder for something better. Note that the map is optional and a shareable link skips it, so anyone sent straight to a checklist will not see this.

• "Add Enrollments" and the invitation link. The Knowledge Base says using Add Enrollments breaks the invitation link. OLI Support believes that may be out of date and wants it tested. The warning on the goLiveDirect step no longer claims the mechanism — it recommends sticking to one enrolment method and says that is current OLI guidance, which is true either way. If the test shows the link is unaffected, the warning can come out altogether.

• The returning-instructor shortcut skips the account and integration questions and goes straight to creating a section, with a fallback to contact OLI if the course isn't visible. Worth confirming this is the right shortcut with the Help Desk.

• Public evaluation copies (for example Arabic 1) are not mentioned in the evaluation path, to keep it short. Add them if they come up often.

• The mailto subject lines ("Torus Evaluation Copy Request," "Torus Instructor Access Request") were chosen to be easy to spot in Zoho Desk. Change them in the mailto section if the Help Desk would rather they matched existing ticket categories.

Article-coverage decisions still open, from comparing the guide against the pathway spec and the full Knowledge Base:

• "Add or Remove Additional Instructors or TAs" is referenced by neither the pathway spec nor this guide, yet faculty routinely add a TA before students arrive. If the Help Desk considers that part of onboarding, it belongs in the configure stage.
• "Synchronizing Torus scores with your LMS gradebook" — the troubleshooting article for when a Torus score and an LMS score disagree — is also in neither document. Step P3 ("Troubleshoot missing work or technical issues") is where it would go — though see the note below about that stage being shared. Note this is a different article from "Syncing Torus Scored Assignments to the LMS Gradebook," which step GL1 already links.
• Three articles the spec cites that this guide deliberately omits: "View Student Assessment Attempts," "Analyze Roster Performance by Question in an Assessment," and "Understanding the Replacement Assessment Setting for Dynamic Variable Questions." All three sit past first setup. If any is wanted, the first two fit step P1 or P2.
• A stale instruction in an article the guide links. The spec flags "Invite Students to a Website Delivery (Direct Delivery) Section" as out of date: it tells instructors to open registration by hand (Manage → Edit Section Details → "Registration Open" and "Requires Enrollment"), which OLI Support says is now the default. An instructor following it will do two unnecessary steps. A one-line note on step GD1 would pre-empt that; the article needs fixing in Zoho.