Arbital lens

https://arbital.com/p/Arbital_lens

by Alexei Andreev Nov 15 2015 updated Dec 5 2016

A lens is a page that presents another page's content from a different angle.


[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.

[toc:]

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:

If you want to create a version that's better fitted for some demographic. For example:

If you want to create a strictly better version. For example:

If you want to create a more terse and technical version. For example:

If you want to add links to external resources. For example:

If you have examples or exercises which don't fit comfortably into the main lens. For example:

When not to create a lens

When you disagree with the content of the page. For example:

When you can only provide a marginal improvement for the primary page. For example:

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:

If you see a lens that fits your background or goal more specifically, it's probably best to start there. For example:


Comments

Emile Kroeger

I expected the "brief" and "summary" preview popups you get when hovering a link to be lenses of the page too… turns out they're a different concept.

Alexei Andreev

Good point. We'll probably have different UI for them at some point.