Orbit Documentation

Orbit lets you interleave recurring prompts into your writing. When used well, these prompts can help people reliably remember what they read, understand complex topics more easily, and stay connected to ideas over time.

This page assumes you're familiar with the general idea; click here for more background on Orbit.

Getting started

Orbit's designed to work anywhere on the web. At the moment, you can embed Orbit using a Web Component which can be used in any HTML page. Setup is easy: add one <script> tag, then you can use special <orbit-reviewarea> and <orbit-prompt> tags anywhere on the page to insert prompts. Here's an example: 

<html>
  <head>
    <script type="module" src="https://js.withorbit.com/orbit-web-component.js"></script>
  </head>
  <body>
    <orbit-reviewarea color="red">
      <orbit-prompt
        question="What's the working name for Andy's experimental mnemonic medium platform?"
        answer="Orbit"
      ></orbit-prompt>
      <orbit-prompt
        question="What kind of quantum gate is this?"
        question-attachments="https://docs.withorbit.com/toffoli.png"
        answer="A Toffoli gate."
      ></orbit-prompt>
      <orbit-prompt
        question="Given a right triangle with legs of length $a$ and $b$, what is the length of hypotenuse $c$?"
        answer="$$c = \sqrt{a^2 + b^2}$$"
      ></orbit-prompt>
    </orbit-reviewarea>
  </body>
</html>

Here's a live demo of the review area that code would produce:

That's it! You can publish that web page as it is. Your readers will be prompted to sign into Orbit if they haven't already. The prompts they answered will be saved to their account. Next time they have prompts ready for review, they'll be notified by email and provided a link to the Orbit review interface, which displays prompts aggregated from all the sites they've visited.

You don't have to do anything special to register your site, though in the future I'll allow you to register URLs so that you can see reader analytics.

While that example can be published as it is, read on to learn more about how to configure Orbit for your web site.

Configuring review areas

Prompts support simple formatting

The question and answer attributes support a subset of Markdown formatting. In particular, you can use inline styling and multiple paragraphs. You can use LaTeX by enclosing inline math in $ symbols and display blocks in $$ symbols, as in the example above. Reserved HTML characters (like >, &, and <) will need to be escaped using entity encodings: for instance, > is written as &gt;.

You can attach an image (PNG, GIF) to the question or answer by specifying a URL using the question-attachments or answer-attachments attribute, as in the example above. You may omit the question or answer attributes if an attachment is present. Note that you must supply an absolute URL, not a relative URL like /toffoli.png. Your image will be cached on Orbit's servers, and changes to its contents may not propagate reliably. If you need to update an image, you should also change its URL.

Support for videos, multiple images, and custom layouts is forthcoming. Please let me know if these absences are blocking you to help me prioritize.

Review areas have colors

You'll notice that review areas have a color attribute. Each site can choose the color it would like its Orbit prompts to be. Then, when readers are reviewing prompts from multiple sites, they'll see your prompts rendered in the color you chose—providing a little bit of context. The supported color values are: red, orange, brown, yellow, lime, green, turquoise, cyan, blue, violet, purple, and pink.

Orbit relies on page metadata

When readers review one of your prompts in their follow-up sessions, Orbit provides context by displaying a link to the page containing those prompts. The interface may also display progress grouped by "source" pages. It's important to make sure that metadata is correct. Here's the information Orbit extracts from your page and how to customize it:

Here's an example <head> demonstrating these values: 

<head>
    <title>Obesity - Our World in Data</title>
    <link rel="canonical" href="https://ourworldindata.org/obesity">
    <meta property="og:title" content="Obesity">
    <meta property="og:site_name" content="Our World in Data">
</head>

You can include multiple review areas on a single page

It's common to use several <orbit-reviewarea> tags on the same page, interleaving them every few hundred words. Orbit currently assumes that all the review areas which appear on a web page should be considered part of the same single piece of content. This works fine for long-form content but will produce confusing results in e.g. a blog layout which displays many posts' contents on one big page. Orbit will eventually allow finer-grained configuration here; please let me know if your site needs this to help me prioritize.

If you have several orbit-reviewareas in one page, you can avoid repeating the color attribute on each of them by specifying the color in the page's <head> tag, like this: 

<head>
  <meta property="orbit:color" content="violet" />
</head>

The current prompt type is meant for memory practice

The existing prompt interface and scheduler are tuned to questions which help people remember and internalize what they read. I believe it's also possible to use Orbit to prompt reflection, self-authorship, texts which extend over time, and so on. Please let me know if you're interested in exploring these use cases; we can figure out how to extend the interface in a way that suits your text.

Testing your prompts

While you're writing and revising your prompts, you may want to enable a "test mode" which won't save of your actions to your account. To do this, append ?orbitDebug to your URL. So for instance, if you're viewing http://you.com/test, point your browser at http://you.com/test?orbitDebug. If the URL already has a ? in it, add &orbitDebug instead, e.g. http://you.com/test?id=4 becomes http://you.com/test?id=4&orbitDebug. And if your web server redirects http://you.com/test to http://you.com/test/, you'll want to visit http://you.com/test/?orbitDebug.

Writing well with Orbit

By introducing Orbit into your writing, you're not just "adding on" a set of flashcards: you're learning to write in a new medium which integrates prose and lightweight exercises. The system only works as well as the prompts you write, and it's deceptively difficult to write them well. You're essentially trying to take all the important ideas you've described in sentences and encode them into questions which, when the reader thinks about them, will reinforce the intended material.

This topic ultimately deserves a small Elements of Style-like book. I've begun by creating a guide to writing good prompts for your own personal study practice: How to write good prompts. Writing good prompts for other people is more challenging. Once I understand those considerations better, I'll write a follow-up guide on that topic. In the meantime, here are a few resources which might be useful:

I'd like to be very involved in early writers' efforts with Orbit. I'm happy to workshop prompts, review drafts, talk technique, etc. Please email me.

🙇👋, Andy