Choose a document, an HTML page or a Lens
Use when you are about to show a person something, or a person asks to see, compare, track or arrange work, and you must choose between a document, an HTML page and a Lens.
The one rule
Documents keep knowledge. HTML pages, html blocks (an HTML file embedded between a document's paragraphs) and objects drawn on a Lens show it. Anything someone will search for, quote, comment on, decide or act on lives in a document, typed when a type fits (When a kind gets its own type). A view may repeat a document's words, but it is never the only place a fact lives. Asked to make something simpler or more visual, add a view and keep the record whole.
Invented content in a mockup, such as placeholder copy or sample numbers, is not a fact. What is decided or found about the mockup is, and it goes into a document.
Pick the smallest form that works
A question gets an answer in chat that names its source documents. Make nothing unless the answer should outlive the chat.
Content to keep goes in a document. Make the record pleasant before reaching for HTML: an images row shows up to six screenshots side by side, a table compares, an html block puts a chart or playground beside the paragraph that argues from it.
To explain or show something is an HTML page: an explanation, a mockup or a mood board, an overview, a snapshot of a dashboard (A whole page that is one HTML file). A page shows, moves and answers in ways a document or a board cannot. When the organization has a website or a brand guide, use them as the page's reference, so it reads in the organization's own style. Its title says what it shows, with the date for a snapshot. Name its sources on the page and link it from the document or Lens it serves.
Work the person returns to over days, to read, plan, arrange or answer, goes on a Lens, and a view they check again and again belongs there as a card. List the organization's Lenses first (
session.listLenses, orsession.focuswith onlyorganizationId) and add to the one on that topic. Make a new one when the person asks, or the second time they come back to the same work.
If a document's text argues around a visual, the visual stays an html block there. If the visual stands alone, it is an HTML page. Never keep two separately made copies of one visual.
Record plus view
The record links its view, so whoever finds the record finds the view. Edit the record first, then redraw the view. Discuss on the record: a comment cannot anchor inside an HTML page, so a question for a person or a note for another agent about what a page shows goes on the block of the record that holds the fact (Ask a person, and keep the answer, Messages between agents).
A live view reads documents while a member has the page open in Oddlynew, through the read channel the page's frame is offered (Read live Oddlynew data). It shows the documents as they are when the page loads. It reads only documents, their types and their metadata, at most 60 reads a minute, so list by type and metadata instead of opening each document. The channel is not offered on a Lens card or a public page, where a live view shows only its fallback. Write the data into the file instead when the view needs images, outside readers, outside numbers or a place on a Lens, and print its date and sources on the page. Outside numbers that people cite go into a document first, for example a weekly row that a recurring agent task (a Loop) writes through the organization's connection to that system (Choose the route to an outside system).
Search reads an HTML page's title, not its file, on purpose, so never count on a page's words being found.
On a Lens
Documents are cards. HTML pages are cards too, at the size you set in the card's placement: two or three landscape explainers can open a board about a problem. A Lens does not explain on its own: an HTML page explains, and the Lens keeps it beside its sources, arranged in a shape that means something, such as a tree from the page down to its sources, lanes, or a row. Drawn objects (frames, lanes, notes and titles bound to no document) point and label: a frame's name, a short note where a reader starts, a few words on an arrow. They never carry an explanation, and a card's label is left out when it would only repeat the card's title or its frame's name. When a document changes, keep its card's label and state current. Work people sort by hand stays as document cards in lanes. An arrow may show that one source supports another, but a relation that matters is written in a document. The board follows Work on a Lens.
Offer another form
Offer once, in one line, after the record exists, and make it only on yes.
The person wants to skim or compare, or the document is a grid of findings or frames: offer an images row, then an HTML page view.
The same overview is asked for again: offer to keep it as a card on a Lens, updated in place.
Work spans three or more documents and will last days: offer a Lens, or a place on an existing one.
A person reacts to something that exists only in a view: write it into its document before acting, and say so.
A one-off page has done its job: offer to archive it. A one-off Lens that has done its job: offer to close it.
Offer nothing for a quick answer, or when the request named its form.
Worked example: a UX check
A site walk produces 33 findings with screenshots, and people act on each. The record is one document with a section per finding: a handle (F01 to F33), the screenshot, what is wrong, the principle it breaks and the fix. A finding's phone and desktop screenshots share one images row. When a fix starts, a task document references that section. If the person wants all findings at a glance, offer an HTML page of small thumbnails, each labeled with its handle, that opens the document when clicked on the page itself. It is a dated snapshot, since the images are copied into the file, and the whole file must stay under 5 MB. If the fixing runs for days, offer a Lens: that page on top as an overview, the UX check below, the tasks as cards with states. On the Lens the page is a card to read; its thumbnails and buttons work when a person opens it.
Before you finish
Every fact you showed lives in a document.
Every HTML page has a telling title, names its sources and is linked from its document or Lens.
You offered at most one other form.