How to author on Arbital!

This is a page about authoring, which for these purposes means, the art of crafting the explanations themselves using Arbital's structure - as opposed to being a guide to the syntax or how to use particular features. To learn about Arbital's special features go to Author's guide to Arbital.

Something to explain

The first thing you need to edit on Arbital is something that you want to explain. Ideally, something that you've been explaining in person over and over again, and in a dozen little comment threads or email threads over and over again, but for which no single central online explanation exists because every different person seems to need a slightly different explanation.

If you have a problem like that and it's making you tear your hair out, then the current version of Arbital is just what you need! Or will be, once a few more features are developed! And we're only going to open it up for math explanations at first, barring special exceptions! But still!

Since Arbital is mostly a green field right now, new projects won't yet be fitting in to a massive repository of existing concepts. You might think that the first step is make a big list of concepts in your field, add tiny little stub pages for everything, and then work on expanding them. Well, we're still figuring out how to use the tool we built, but at least Eliezer Yudkowsky reports that trying to use Arbital that way wasn't actually much fun. What's more fun is taking on a project that's small enough, and basic enough, that you can get it to a completed state in less than a year. If you need to create stub pages in the course of doing that, with small summaries of the concepts to be expanded later, that's fine - but your first priority should be to find a finishable chunk of explanation that you can put online. Remember, you should in the first place be trying to set down the explanation for some particular thing that you've explained repeatedly before.

Getting organized

If you look at the Bayes Rule Guide, you'll see some really neat questionnaires and requisites that turn into paths of learning and you'll want to set those up on your own. Great, but don't go overboard in the planning phase on figuring out subtle requisites to distinguish! You'll observe that the Bayes's Rule Guide is stratified mostly by a single core differentiator, the level of math knowledge; and that the questionnaire asks about a few more things beyond that, like logic or calculus. The further requisites are mostly trails that build on each other. Keeping the complexity of the entire pattern to a minimum was part of the work!

If you're the sort of person who outlines, it's probably a good idea to sketch out a very quick list of what you might write. One good way of organizing this is for the high-level items to be a sort of generic path, and then the subitems to be concepts that will appear for different audiences. For example, an early sketch for Bayes's Rule might look like:

• stratify by:
• Math 0-3
• algebra, logic, calculus, prior knowledge of conditional probability
• whether they just already know Bayes's Rule
• start by showing some example problems at levels above Math 0
• diagrams for waterfalls and frequencies
• odds ratios versus probabilities
• diagrams for odds ratios (mainly important for Math 1, but can show briefly at Math 2)
• formal definition of conditional probabilities
• we can slip this into Math 2 before the proof, but need to have it come after the first Bayes's Rule examples in Math 1
• …

Yudkowsky found that it was often helpful to start on 'basic' pages before doing the later pages that took the early ones as requisites, because then he had a good idea what he'd already explained. Editing in Arbital isn't always very linear, and there were plenty of times when Yudkowsky stopped to create a new stub page to fill in later so he could link it right away, or create pages that were there to provide compact summaries of concepts rather than being part of anyone's learning path. But still, starting with the earlier pages seemed generally productive.

Write the fun version

So now you're tackling a particular concept page! With multiple versions! When you're doing that, there'll usually be one version that you find easiest to write first. It could be that you'll have the easiest time starting at a lower technical level, and then compressing that explanation to yield the faster, high-level technical explanation - that your nature is to find yourself slowing down to explain details, if your brain doesn't think it's explained them already. You might also find it faster to speak technical language and easiest to write the most technical version of the page first. Whatever works for you! Yudkowsky definitely found that it seemed better to write the page first and then go back and create the [summary: ] section at the top, but you never know, mileage might vary.

(Since the Main page is always the most technical, this may mean that at some point you realize you've written a less technical page that isn't the real Main page, and you'll create a new Lens, copy the current text, and paste it into the Lens. Then you'll need to go back and write a new Main page. All we can say is, yeah, that happens sometimes, and in the near future we'll have a more streamlined process to do this.)

If a page doesn't seem fun to write, stop and think. Is the reader going to have fun reading this? Are you maybe going into too much detail, or are you keeping the discussion too abstract? Remember, part of the concept of Arbital is that we can differentiate pages based on the audience, and that means, among other things, that there should always be room for the version that's the most fun to write. You can leave out all the fiddly details that slow things down, and add conditional text or a different version of the page that puts them back in. You can see whether the fun version of the page maybe just works, or if people add questions and confusions indicating that you need to amplify - and then you'll know where expansion is really needed. You can create the informal version of the page without worrying about it looking less encyclopedic, because if someone wants a technical-looking dry version of the page, there can be a lens for that. You can throw in the beautiful corollary of the proof for the most technical reader - if that's losing some readers, you can embed the digression in a conditional for people who want more details or have a higher math level. Again, it's obviously possible to go overboard and you should try to keep the number of proliferating versions down - but the notion that at least one lens should be the one that was fun to write can be quite useful.

Greenlinks and tags

Arbital's greenlinks are another tool for eliminating duplicated effort and letting you address more than one audience at a time. Not every page needs to contain a full disclaimer about how the natural numbers are (0, 1, 2, 3…) but not any negative numbers, if you have a greenlink for that. Not every page needs to repeat the definition of conditional probability, if you have a greenlink for that. These are best for the case where most of your readers probably understand the greenlinked term, but some people might be coming in unawares. If that's the situation, but the necessary concept is one whose gist can be picked up quickly, you don't necessarily need to add a requisite - you can just use a greenlink, and the unfamiliar reader will hover it and read the summary (at least that's what we hope). Remember, requisites aren't proof steps - the point isn't to make a requisite out of every concept used in the proof, requisites are there to describe minimum paths for people learning things. If you can pick up the idea by reading a greenlink summary, that idea shouldn't be a requisite!

Arbital's tags, at this present time, are something of a feature under construction. The basic rule is that a tag should be applied to a page when you'd want somebody learning about the tagging concept to read through the tagged page in order to understand the tagging concept. Not every page that uses natural numbers should be tagged 'natural numbers'. But a page on the Peano Axioms? A page distinguishing standard numbers from nonstandard numbers? That might be a good one to tag with 'natural_numbers'. You'd want somebody reading up on the natural numbers and looking for related pages to visit a page on Peano axioms, so Peano axioms are a good page to tag with 'natural numbers'.

More to come

(this page is itself a work in progress…)