Arbital lens

Each reader of a page ar­rives with a differ­ent set of things they already know. It’s im­pos­si­ble for one page to cater to ev­ery­one. For this rea­son, we have lenses, which provide a differ­ent view of the same sub­ject. Usu­ally, differ­ent lenses will have differ­ent re­quire­ments. You are look­ing at the pri­mary lens for “Ar­bital lens” right now. There is a lens ti­tled “TL;DR” (too long; didn’t read) just to show you what lenses can do. Click on it to see what switch­ing lenses looks like.

Each page has a pri­mary lens, which should be aimed at the au­di­ence most likely to be view­ing it (for an ad­vanced con­cept like par­tially or­dered set this means us­ing ap­pro­pri­ate no­ta­tion and jar­gon, and for one with a wider in­ter­ested au­di­ence like ad­di­tion ex­plain­ing in less tech­ni­cal terms). The pri­mary lens should ei­ther link to, ex­plain, or sum­ma­rize rele­vant con­cepts ex­plained on any of the page’s other lenses (e.g. link to a lens with a proof), so that a reader can find all of Ar­bital’s in­for­ma­tion with­out ex­plor­ing lenses in an undi­rected way.

For large con­cepts like log­a­r­ithm the main lens should have a mostly neu­tral (but still en­gag­ing, don’t try to sound for­mal or dry) voice and should give a high-level de­scrip­tion, some mo­ti­vat­ing ex­am­ples. It should offer routes to a bunch of other pages ex­plain­ing differ­ent as­pects of the thing speci­fi­cally; and should have var­i­ous lenses which give an easy in­tro, a fast tech­ni­cal in­tro, ex­er­cises, and ex­am­ples.

For smaller con­cepts, where a rea­son­ably sized page can cover all ma­jor parts of the topic, hav­ing a more con­ver­sa­tional style and jump­ing right into ex­plain­ing it to the most rele­vant au­di­ence is en­couraged, but al­ter­nate ap­proaches are wel­come if they work well for the rele­vant au­di­ence (e.g. hav­ing ex­am­ple and ex­er­cise lenses).

Creat­ing a lens

To cre­ate a lens go to edit the page you want to have a lens, then click to the Re­la­tion­ships tab and add the page you want to make into a lens as a child. Then click the check­box to make it a lens click the lens name to re­name it to some­thing ap­pro­pri­ate.

When to cre­ate a lens

If you think the cur­rent lenses are not well-suited for some au­di­ence who may want to un­der­stand the topic. For ex­am­ple:

  • A very math-heavy page on “Prob­a­bil­ity” is hard to un­der­stand for peo­ple who aren’t already very good at math. You can cre­ate a lens that as­sumes only ba­sic knowl­edge of ar­ith­metic, and guide the reader slowly through lots of ex­am­ples and pic­tures.

If you want to cre­ate a ver­sion that’s bet­ter fit­ted for some de­mo­graphic. For ex­am­ple:

  • A page about teach­ing mas­sage tech­niques can have a lens that will be more effec­tive and pre­cise for peo­ple who have stud­ied hu­man anatomy.

If you want to cre­ate a strictly bet­ter ver­sion. For ex­am­ple:

  • You look at the page ti­tled “Rick and Morty (TV se­ries)”, and it’s poorly writ­ten, has no struc­ture, and ram­bles on about how great the show is. More­over, it has 150 likes but is marked as a stub. You think you can do bet­ter, but in­stead of edit­ing the ex­ist­ing page, which is be­yond re­pair, you cre­ate a new lens and write a whole new de­scrip­tion. It gets 200 likes in a week, and soon be­comes the pri­mary lens for “Rick and Morty (TV se­ries)” page.

If you want to cre­ate a more terse and tech­ni­cal ver­sion. For ex­am­ple:

  • The main lens on Un­countabil­ity is a full wordy ex­pla­na­tion, and you think peo­ple with a strong math back­ground would like a brief no­ta­tion-heavy for­mal defi­ni­tion.

  • The main lens on the­o­rem gives only gives an in­for­mal proof, and you want to cre­ate a page with a for­mal proof.

If you want to add links to ex­ter­nal re­sources. For ex­am­ple:

  • You’ve found a great ex­pla­na­tion of Euler’s For­mula on Bet­terEx­plained, and think that it would he helpful to Ar­bital’s read­ers, so you add an ex­ter­nal re­source lens with a brief de­scrip­tion of each link (note: re­sources lenses should never be the main lens, cre­ate at least a stub page with a sum­mary for popovers be­fore adding them).

If you have ex­am­ples or ex­er­cises which don’t fit com­fortably into the main lens. For ex­am­ple:

When not to cre­ate a lens

When you dis­agree with the con­tent of the page. For ex­am­ple:

  • The page about the cause of global warm­ing strongly con­cludes that it’s an­thropic. If you dis­agree with the con­clu­sion, use the vot­ing fea­ture, or if you think the page was poorly writ­ten and it’s not already marked for im­prove­ment then re­quest a qual­ity check. You are wel­come to cre­ate an­other page dis­cussing your dis­agree­ment or pro­vid­ing an al­ter­na­tive view, just don’t make it a lens.

When you can only provide a marginal im­prove­ment for the pri­mary page. For ex­am­ple:

  • You would re-use sig­nifi­cant parts of an ex­ist­ing lens, with changes which are gen­eral im­prove­ments. Just edit the pri­mary page, un­less your new lens would be both sig­nifi­cantly bet­ter for some read­ers and no­tably worse for oth­ers.

Some­times it can be un­clear if one page should be con­sid­ered a lens for an­other; or if one page needs a cer­tain lens. If you run into a case you can’t clearly re­solve, please com­ment on this page, so we can dis­cuss it, learn from it, and re­fine these defi­ni­tions.

When to con­sider read­ing a differ­ent lens

If you look at the page and you don’t un­der­stand it, con­sider find­ing a sim­pler lens. Lenses will of­ten have differ­ent re­quire­ments. For ex­am­ple:

  • You stum­ble onto the Orthog­o­nal­ity Th­e­sis page and quickly be­come con­fused. If there is a sim­pler lens, switch to it, so you can still get the main gist of the con­cept and see if you want to spend the time catch­ing up on the re­quire­ments to un­der­stand this topic at a more tech­ni­cal level.

If you see a lens that fits your back­ground or goal more speci­fi­cally, it’s prob­a­bly best to start there. For ex­am­ple:

  • “Learn­ing An­droid app de­vel­op­ment” page has a lens called “For peo­ple that know iOS app de­vel­op­ment”. If you have pre­vi­ously de­vel­oped apps for iOS, then read­ing that lens will be bet­ter, since the au­thor can lev­er­age your ex­ist­ing knowl­edge to teach you faster.

  • Another lens for the same page ti­tled “For cre­at­ing so­cial net­work apps” will be more use­ful for the per­son look­ing to build a so­cial net­work app on An­droid than the catch-all pri­mary lens.