How to author on Arbital!

This is a page about au­thor­ing, which for these pur­poses means, the art of craft­ing the ex­pla­na­tions them­selves us­ing Ar­bital’s struc­ture—as op­posed to be­ing a guide to the syn­tax or how to use par­tic­u­lar fea­tures. To learn about Ar­bital’s spe­cial fea­tures go to Author’s guide to Ar­bital.

Some­thing to explain

The first thing you need to edit on Ar­bital is some­thing that you want to ex­plain. Ideally, some­thing that you’ve been ex­plain­ing in per­son over and over again, and in a dozen lit­tle com­ment threads or email threads over and over again, but for which no sin­gle cen­tral on­line ex­pla­na­tion ex­ists be­cause ev­ery differ­ent per­son seems to need a slightly differ­ent ex­pla­na­tion.

If you have a prob­lem like that and it’s mak­ing you tear your hair out, then the cur­rent ver­sion of Ar­bital is just what you need! Or will be, once a few more fea­tures are de­vel­oped! And we’re only go­ing to open it up for math ex­pla­na­tions at first, bar­ring spe­cial ex­cep­tions! But still!

Since Ar­bital is mostly a green field right now, new pro­jects won’t yet be fit­ting in to a mas­sive repos­i­tory of ex­ist­ing con­cepts. You might think that the first step is make a big list of con­cepts in your field, add tiny lit­tle stub pages for ev­ery­thing, and then work on ex­pand­ing them. Well, we’re still figur­ing out how to use the tool we built, but at least Eliezer Yud­kowsky re­ports that try­ing to use Ar­bital that way wasn’t ac­tu­ally much fun. What’s more fun is tak­ing on a pro­ject that’s small enough, and ba­sic enough, that you can get it to a com­pleted state in less than a year. If you need to cre­ate stub pages in the course of do­ing that, with small sum­maries of the con­cepts to be ex­panded later, that’s fine—but your first pri­or­ity should be to find a finish­able chunk of ex­pla­na­tion that you can put on­line. Re­mem­ber, you should in the first place be try­ing to set down the ex­pla­na­tion for some par­tic­u­lar thing that you’ve ex­plained re­peat­edly be­fore.

Get­ting organized

If you look at the Bayes Rule Guide, you’ll see some re­ally neat ques­tion­naires and req­ui­sites that turn into paths of learn­ing and you’ll want to set those up on your own. Great, but don’t go over­board in the plan­ning phase on figur­ing out sub­tle req­ui­sites to dis­t­in­guish! You’ll ob­serve that the Bayes’s Rule Guide is strat­ified mostly by a sin­gle core differ­en­tia­tor, the level of math knowl­edge; and that the ques­tion­naire asks about a few more things be­yond that, like logic or calcu­lus. The fur­ther req­ui­sites are mostly trails that build on each other. Keep­ing the com­plex­ity of the en­tire pat­tern to a min­i­mum was part of the work!

If you’re the sort of per­son who out­lines, it’s prob­a­bly a good idea to sketch out a very quick list of what you might write. One good way of or­ga­niz­ing this is for the high-level items to be a sort of generic path, and then the subitems to be con­cepts that will ap­pear for differ­ent au­di­ences. For ex­am­ple, an early sketch for Bayes’s Rule might look like:

  • strat­ify by:

  • Math 0-3

  • alge­bra, logic, calcu­lus, prior knowl­edge of con­di­tional probability

  • whether they just already know Bayes’s Rule

  • start by show­ing some ex­am­ple prob­lems at lev­els above Math 0

  • di­a­grams for wa­ter­falls and frequencies

  • odds ra­tios ver­sus probabilities

  • di­a­grams for odds ra­tios (mainly im­por­tant for Math 1, but can show briefly at Math 2)

  • for­mal defi­ni­tion of con­di­tional probabilities

  • we can slip this into Math 2 be­fore the proof, but need to have it come af­ter the first Bayes’s Rule ex­am­ples in Math 1

Yud­kowsky found that it was of­ten helpful to start on ‘ba­sic’ pages be­fore do­ing the later pages that took the early ones as req­ui­sites, be­cause then he had a good idea what he’d already ex­plained. Edit­ing in Ar­bital isn’t always very lin­ear, and there were plenty of times when Yud­kowsky stopped to cre­ate a new stub page to fill in later so he could link it right away, or cre­ate pages that were there to provide com­pact sum­maries of con­cepts rather than be­ing part of any­one’s learn­ing path. But still, start­ing with the ear­lier pages seemed gen­er­ally pro­duc­tive.

Write the fun version

So now you’re tack­ling a par­tic­u­lar con­cept page! With mul­ti­ple ver­sions! When you’re do­ing that, there’ll usu­ally be one ver­sion that you find eas­iest to write first. It could be that you’ll have the eas­iest time start­ing at a lower tech­ni­cal level, and then com­press­ing that ex­pla­na­tion to yield the faster, high-level tech­ni­cal ex­pla­na­tion—that your na­ture is to find your­self slow­ing down to ex­plain de­tails, if your brain doesn’t think it’s ex­plained them already. You might also find it faster to speak tech­ni­cal lan­guage and eas­iest to write the most tech­ni­cal ver­sion of the page first. What­ever works for you! Yud­kowsky definitely found that it seemed bet­ter to write the page first and then go back and cre­ate the [sum­mary: ] sec­tion at the top, but you never know, mileage might vary.

(Since the Main page is always the most tech­ni­cal, this may mean that at some point you re­al­ize you’ve writ­ten a less tech­ni­cal page that isn’t the real Main page, and you’ll cre­ate a new Lens, copy the cur­rent 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 hap­pens some­times, and in the near fu­ture we’ll have a more stream­lined pro­cess to do this.)

If a page doesn’t seem fun to write, stop and think. Is the reader go­ing to have fun read­ing this? Are you maybe go­ing into too much de­tail, or are you keep­ing the dis­cus­sion too ab­stract? Re­mem­ber, part of the con­cept of Ar­bital is that we can differ­en­ti­ate pages based on the au­di­ence, and that means, among other things, that there should always be room for the ver­sion that’s the most fun to write. You can leave out all the fiddly de­tails that slow things down, and add con­di­tional text or a differ­ent ver­sion of the page that puts them back in. You can see whether the fun ver­sion of the page maybe just works, or if peo­ple add ques­tions and con­fu­sions in­di­cat­ing that you need to am­plify—and then you’ll know where ex­pan­sion is re­ally needed. You can cre­ate the in­for­mal ver­sion of the page with­out wor­ry­ing about it look­ing less en­cy­clo­pe­dic, be­cause if some­one wants a tech­ni­cal-look­ing dry ver­sion of the page, there can be a lens for that. You can throw in the beau­tiful corol­lary of the proof for the most tech­ni­cal reader—if that’s los­ing some read­ers, you can em­bed the di­gres­sion in a con­di­tional for peo­ple who want more de­tails or have a higher math level. Again, it’s ob­vi­ously pos­si­ble to go over­board and you should try to keep the num­ber of pro­lifer­at­ing ver­sions down—but the no­tion that at least one lens should be the one that was fun to write can be quite use­ful.

Green­links and tags

Ar­bital’s green­links are an­other tool for elimi­nat­ing du­pli­cated effort and let­ting you ad­dress more than one au­di­ence at a time. Not ev­ery page needs to con­tain a full dis­claimer about how the nat­u­ral num­bers are (0, 1, 2, 3…) but not any nega­tive num­bers, if you have a green­link for that. Not ev­ery page needs to re­peat the defi­ni­tion of con­di­tional prob­a­bil­ity, if you have a green­link for that. Th­ese are best for the case where most of your read­ers prob­a­bly un­der­stand the green­linked term, but some peo­ple might be com­ing in un­awares. If that’s the situ­a­tion, but the nec­es­sary con­cept is one whose gist can be picked up quickly, you don’t nec­es­sar­ily need to add a req­ui­site—you can just use a green­link, and the un­fa­mil­iar reader will hover it and read the sum­mary (at least that’s what we hope). Re­mem­ber, req­ui­sites aren’t proof steps—the point isn’t to make a req­ui­site out of ev­ery con­cept used in the proof, req­ui­sites are there to de­scribe min­i­mum paths for peo­ple learn­ing things. If you can pick up the idea by read­ing a green­link sum­mary, that idea shouldn’t be a req­ui­site!

Ar­bital’s tags, at this pre­sent time, are some­thing of a fea­ture un­der con­struc­tion. The ba­sic rule is that a tag should be ap­plied to a page when you’d want some­body learn­ing about the tag­ging con­cept to read through the tagged page in or­der to un­der­stand the tag­ging con­cept. Not ev­ery page that uses nat­u­ral num­bers should be tagged ‘nat­u­ral num­bers’. But a page on the Peano Ax­ioms? A page dis­t­in­guish­ing stan­dard num­bers from non­stan­dard num­bers? That might be a good one to tag with ‘nat­u­ral_num­bers’. You’d want some­body read­ing up on the nat­u­ral num­bers and look­ing for re­lated pages to visit a page on Peano ax­ioms, so Peano ax­ioms are a good page to tag with ‘nat­u­ral num­bers’.

More to come

(this page is it­self a work in progress…)