[summary: Each reader arrives with a different set of background assumptions and things they already know. Arbital lenses allow authors to tailor different explanations for different readers, with that reader's Arbital requisites determining which page is shown by default. Most commonly, a page will have multiple explanations at different technical levels. The "Primary" page should always be the most complete.]
[summary(Brief): Arbital lenses allow for different page versions aimed at different readers, with Arbital requisites helping select which one is shown by default.]
Each reader of a page arrives with a different set of things they already know. It's impossible for one page to cater to everyone. For this reason, we have lenses, which provide a different view of the same subject. Usually, different lenses will have different requirements. You are looking at the primary lens for "Arbital lens" right now. There is a lens titled "TL;DR" (too long; didn't read) just to show you what lenses can do. Click on it to see what switching lenses looks like.
Each page has a primary lens, which should be aimed at the audience most likely to be viewing it (for an advanced concept like Partially ordered set this means using appropriate notation and jargon, and for one with a wider interested audience like [-addition] explaining in less technical terms). The primary lens should either link to, explain, or summarize relevant concepts explained 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 Arbital's information without exploring lenses in an undirected way.
For large concepts like Logarithm the main lens should have a mostly neutral (but still engaging, don't try to sound formal or dry) voice and should give a high-level description, some motivating examples. It should offer routes to a bunch of other pages explaining different aspects of the thing specifically; and should have various lenses which give an easy intro, a fast technical intro, exercises, and examples.
For smaller concepts, where a reasonably sized page can cover all major parts of the topic, having a more conversational style and jumping right into explaining it to the most relevant audience is encouraged, but alternate approaches are welcome if they work well for the relevant audience (e.g. having example and exercise lenses).
Creating a lens
To create a lens go to edit the page you want to have a lens, then click to the Relationships tab and add the page you want to make into a lens as a child. Then click the checkbox to make it a lens click the lens name to rename it to something appropriate.
When to create a lens
If you think the current lenses are not well-suited for some audience who may want to understand the topic. For example:
- A very math-heavy page on "Probability" is hard to understand for people who aren't already very good at math. You can create a lens that assumes only basic knowledge of arithmetic, and guide the reader slowly through lots of examples and pictures.
If you want to create a version that's better fitted for some demographic. For example:
- A page about teaching massage techniques can have a lens that will be more effective and precise for people who have studied human anatomy.
If you want to create a strictly better version. For example:
- You look at the page titled "Rick and Morty (TV series)", and it's poorly written, has no structure, and rambles on about how great the show is. Moreover, it has 150 likes but is marked as a Stub. You think you can do better, but instead of editing the existing page, which is beyond repair, you create a new lens and write a whole new description. It gets 200 likes in a week, and soon becomes the primary lens for "Rick and Morty (TV series)" page.
If you want to create a more terse and technical version. For example:
- The main lens on Uncountability is a full wordy explanation, and you think people with a strong math background would like a brief notation-heavy Formal definition.
- The main lens on [Pythagorean theorem] gives only gives an informal proof, and you want to create a page with a formal proof.
If you want to add links to external resources. For example:
- You've found a great explanation of Euler's Formula on BetterExplained, and think that it would he helpful to Arbital's readers, so you add an [arbital_external_resources external resource] lens with a brief description of each link (note: resources lenses should never be the main lens, create at least a stub page with a summary for popovers before adding them).
If you have examples or exercises which don't fit comfortably into the main lens. For example:
- You want to put up some examples of associativity, but don't think they'd fit well into the current main lens, so you create an examples lens.
- You want to add some exercises to Join and meet but don't think they'd fit well into the current main lens, so you create an exercises lens.
When not to create a lens
When you disagree with the content of the page. For example:
- The page about the cause of global warming strongly concludes that it's anthropic. If you disagree with the conclusion, use the voting feature, or if you think the page was poorly written and it's not already marked for improvement then request a quality check. You are welcome to create another page discussing your disagreement or providing an alternative view, just don't make it a lens.
When you can only provide a marginal improvement for the primary page. For example:
- You would re-use significant parts of an existing lens, with changes which are general improvements. Just edit the primary page, unless your new lens would be both significantly better for some readers and notably worse for others.
Sometimes it can be unclear if one page should be considered a lens for another; or if one page needs a certain lens. If you run into a case you can't clearly resolve, please comment on this page, so we can discuss it, learn from it, and refine these definitions.
When to consider reading a different lens
If you look at the page and you don't understand it, consider finding a simpler lens. Lenses will often have different requirements. For example:
- You stumble onto the Orthogonality Thesis page and quickly become confused. If there is a simpler lens, switch to it, so you can still get the main gist of the concept and see if you want to spend the time catching up on the requirements to understand this topic at a more technical level.
If you see a lens that fits your background or goal more specifically, it's probably best to start there. For example:
- "Learning Android app development" page has a lens called "For people that know iOS app development". If you have previously developed apps for iOS, then reading that lens will be better, since the author can leverage your existing knowledge to teach you faster.
- Another lens for the same page titled "For creating social network apps" will be more useful for the person looking to build a social network app on Android than the catch-all primary lens.