Work on a Lens

Use when you are about to show a person work on a Lens, or when the person wants to read, plan and arrange something with you over days or weeks rather than look at it once.

A Lens is a long-lived space to read content, plan and arrange it. It is not a design tool. The person comes back to it, and so do you. The calls are in the Lens and Session manuals (guide({ explain: "lens" }), guide({ explain: "session" })); this page is about using them well.

Lens, HTML page or document

A Lens is for work the person comes back to; one thing to look at is an HTML page, and knowledge lives in documents. How to choose, and when to offer another form: Choose a document, an HTML page or a Lens.

Three kinds of things on a Lens

Documents carry the knowledge. They are cards, set with session.focus.
HTML page documents carry what is made to be looked at: explanations, mockups, dashboards, overviews. To explain something visually, make an HTML page, in the organization's own style when it has a website or a brand guide, and put it on the Lens beside its sources. They are cards too.
Lens HTML objects, drawn with lens.draw, are plain visual guidance: a frame, a lane, a note, a title. They are bound to no document. They point and label; they never carry an explanation on their own, which belongs in an HTML page.

A drawn object is never the only home of a fact. It is not searched, not versioned and gone when erased. When something on the board becomes knowledge (a decision, a number, a rule), write it into the document that owns it first, then draw from that document.

Lead with one overview

The first thing a person sees should say what the Lens is for and where to start: one overview document, or a label title with a short note beside the documents it introduces. Put it where the board opens and keep everything else around it. A Lens with no clear start reads as a pile.

Build every Lens with handover quality: someone who has no context, asking for "a Lens of what my colleague is working on", understands what is going on and where it stands without being flooded, and knows what to open or ask next. Name each part with one labeled card instead of putting every document on the board (Handover quality).

Label a card when the label adds something

Give a card a label when it says what the card is for on this board and its title does not, such as "Decision: three plans or two" or "Mockup: checkout, second try", and a state when it has one (needs-you, under-way, blocked, done, parked). Leave the label out when it would only repeat the card's title or the name of the frame it sits in: the board then shows the same words twice. What a person reads when the whole board is in view should make sense without opening the card.

Patterns that work

Arrange by how understanding should move (Common document topologies).

Start here for a board that explains a problem: from the top down. At the top, put two or three HTML page documents side by side, each a landscape card at desktop size (for example 1440 by 900) that explains one part of the problem. Below them, put a short note and the recommendation document they lead to. Below that, pack the source documents densely as small cards, for example dozens of short feedback documents. From far away they read as the body of evidence, and the person zooms in to read any one of them. A card's placement sets its width and height, from 240 by 180 up. A Lens holds at most 100 cards, so when the sources are more, put a document that gathers them on the board instead.

Other shapes:

A tree: the HTML page that explains at the top, its sources below it in frames by the question each answers, connected from the page to each frame.
A ring: the one thing being judged in the middle, its evidence, decisions and open questions around it.
A chain: steps from left to right, in order.
Lanes: one row per workstream or owner, a label at the head of each, and a frame with layer: "under" around the row.
A pyramid: the conclusion on top, the reasons in a row under it, the evidence at the base.
A door to another Lens: when a board grows a second job, give that job its own Lens and draw a door to it instead of crowding both onto one.

Combine shapes only when each has a clear job.

Keep it current and respect what the person placed

Before making a Lens, list the organization's Lenses (session.listLenses) and add to the one on that topic.
Read the whole board with lens.read before every change, following nextCursor to the last page.
Draw in the free regions the read returns, and fix the warnings your own objects cause.
A card or object a person placed (placedBy: "human") is their arrangement and tells you what they mean. Leave it where it is. Move it only when they ask, with movePersonPlaced: true.
Connections a person drew count as theirs: merge them into yours rather than replacing them.
When the documents change, redraw the groups that show them and update the cards' labels and states. Erase guidance that has done its job.
When the person comes back, tell them what changed since they last looked (you.unseen), and record what they saw with lens.seen.

Move the camera sparingly

The view belongs to the person. Use lens.camera only to show what you just made or what they asked to see, once; otherwise say in words where to look. After each change a reader would notice, look at the board with lens.look, with a designer's eye, and fix what reads badly before you say it is done.

Before you finish

Every fact on the board lives in a document.
Every card's title or label says what it is for, and no label repeats a title or a frame's name.
One overview leads the board.
No warning names an object you drew.
The person has the Lens url.