Author's guide to Arbital

This page briefly cov­ers the what, why, and how of con­tribut­ing to Ar­bital’s quickly-grow­ing repos­i­tory of math ex­pla­na­tions.

Why Ar­bital?

Ar­bital’s cur­rent fo­cus in on solv­ing on­line ex­pla­na­tion. If you check out Ar­bital’s Guide to Bayes’ rule and con­trast that with the Wikipe­dia en­try on Bayes’ rule, you’ll get a quick pic­ture of the new di­rec­tion Ar­bital is head­ing. The cur­rent pro­to­type already pro­vides the best URL on the In­ter­net if you need to point a read­er­ship (not just an in­di­vi­d­ual) at an ex­pla­na­tion of Bayes’ rule. Fu­ture ex­pla­na­tions and dis­cus­sions can build on top that.

Ar­bital is cur­rently in beta, so don’t be too sur­prised if some things are bro­ken or con­fus­ing, and please do send us feed­back! The eas­iest way to do that is via the Quick Menu but­ton (bot­tom right), but use what­ever method is most con­ve­nient for you. There is also a Slack chan­nel where you can talk to the team and other ed­i­tors.

What should I write?

See also: Ex­em­plar pages

Right now, ar­bital is fo­cus­ing on math con­tent. Within the do­main of math, our first piece of ad­vice is this: ex­plain a con­cept that you’d be ex­cited to ex­plain. If you have an in­tu­itive ex­pla­na­tion of why \(e\) is \(\approx 2.718...\) that you’ve always wished more peo­ple would be able to find, write it up. If you’re itch­ing for hu­man­ity to have easy ac­cess to a com­pel­ling ex­pla­na­tion of the un­solv­abil­ity of the quin­tic, write it up. If you don’t know ex­actly how it’s go­ing to go yet, that’s OK — ex­plain­ing things is a great way to learn them deeply.

If you don’t have any par­tic­u­lar math­e­mat­i­cal itch to scratch, the eas­iest way to con­tribute is to fill out a red link on a topic that you’re fa­mil­iar with. The most-linked-to miss­ing pages are listed on the front page of Ar­bital.

How should I write?

All logged in users can cre­ate pages. Ar­bital pages are writ­ten in Ar­bital Mark­down.noteMany of ar­bital’s ex­ten­sions to mark­down are un­der heavy de­vel­op­ment. The stan­dard mark­down stuff is sta­ble, but fea­tures such as con­di­tional text may change over time. The toolbar in the ed­i­tor will help you fa­mil­iarize your­self with Ar­bital mark­down syn­tax if you don’t know it already. The most im­por­tant fea­ture is the “in­tr­a­site link” but­ton which al­lows you to search for ex­ist­ing pages and in­sert a green­link to them.

By de­fault, when you cre­ate a page, it will be un­listed. You may sub­mit it to the math do­main when it’s ready for read­ers. It will be re­viewed by Ar­bital’s math com­mu­nity, and, prob­a­bly af­ter some feed­back, ac­cepted into the math do­main, at which point it will be­come visi­ble to the pub­lic.

How should I edit?

Ar­bital is a col­lab­o­ra­tive plat­form. You can sug­gest changes to any page, and once you’ve made a few good ed­its we’ll pro­mote you to trusted sta­tus so you’ll also have the op­tion to di­rectly edit most of our con­tent (though it’ll still be checked over by a mem­ber of the re­view team).

If you see some­thing you think you could im­prove, jump in and change it! And don’t fret: we save all page his­tory, so we can re­cover the old text if some­thing goes wrong.

More info

Ar­bital has quite a few mov­ing parts. You can prob­a­bly figure them on as you go, but if you are the kind of per­son who likes to read the man­ual first, this guide will run you through all the ba­sics. <div>

%%!knows-req­ui­site(Author’s guide to Ar­bital ex­pla­na­tions): Above all else, Ar­bital ex­cels in us­ing its ex­ist­ing page struc­ture and con­nec­tions to dy­nam­i­cally cre­ate per­son­ally tai­lored ex­pla­na­tions. To un­der­stand how Ar­bital does that and to see how you can cre­ate your own ex­pla­na­tions read this guide. %%

%%!knows-req­ui­site(Author’s guide to pro­cess­ing feed­back): Part of what makes Ar­bital differ­ent is how easy it is for users to give feed­back in var­i­ous forms. To learn about var­i­ous feed­back mechanisms and how to make your pages and ex­pla­na­tions bet­ter, read this guide. %%

%%!knows-req­ui­site(Author’s guide to Ar­bital: Ad­vanced): To learn about Ar­bital’s ad­vanced fea­tures, read this guide. %%