Field Notes

meta

Reading interface redesign proposals

StatusWorkingUpdatedStands on5 sourcesSupportsnotes

This note records what three design explorations found about how the wiki should render itself, and which of their proposals were adopted. The renderer they concern is described in Build and rendering pipeline; this note is about what it should produce, not how it works.

The explorations ran in reverse order of confidence. Style-led wiki redesign mockups began from screenshots of the interface and changed its appearance. Feature-driven wiki mockups began from AGENTS.md and drew capabilities the wiki documents but had never rendered. Wiki reading interface prototypes began from a brief stating only the content model, the corpus measurements, and the reading tasks, and produced four working pages by four agents who were told not to read the repository. Each step removed more of the existing design from the input, and the third removed it entirely.

Why the third exploration was run blind

An interface that already exists is a strong prior. The first exploration supplied it directly, as screenshots, and its own record notes the consequence: the conventional navigation and reading hierarchy survived, and the useful contributions were narrow — pinning, page furniture, and signalling a note’s kind through more than colour.

The third exploration removed that prior to find out which parts of the arrangement were load-bearing. Four agents received one brief and four different starting questions: sustained reading, corpus navigation, epistemic standing, and an instruction to assume the conventional answer is wrong. Divergence was the point. Where four designers who could not see each other’s work and could not see the existing interface nonetheless arrived at the same answer, that answer is evidence rather than taste.

Four independent designs for the same note, rendered at 1440 pixels

What the corpus requires

The brief carried measurements rather than adjectives, and those measurements decided more of the outcome than any preference did.

The vault is not a set of long essays. Its median note runs 342 words, its ninetieth percentile 1,185, and only 36 notes of 554 exceed 1,500. Sixty-one percent of it is source and entity cards, which are the short ones. The 3,400-word synthesis that a designer naturally reaches for as the representative case is the exception, and a layout tuned to it is tuned to about one note in fifteen.

Section structure follows from that. Thirty-five percent of notes carry no heading at all, and half carry two or fewer:

{
  "data": {"values": [
    {"headings": "0", "notes": 194}, {"headings": "1", "notes": 10},
    {"headings": "2", "notes": 68}, {"headings": "3", "notes": 83},
    {"headings": "4", "notes": 76}, {"headings": "5", "notes": 34},
    {"headings": "6", "notes": 27}, {"headings": "7", "notes": 16},
    {"headings": "8", "notes": 9}, {"headings": "9", "notes": 9},
    {"headings": "10", "notes": 8}, {"headings": "11", "notes": 3},
    {"headings": "12", "notes": 1}, {"headings": "13+", "notes": 16}
  ]},
  "mark": {"type": "bar", "tooltip": true},
  "encoding": {
    "x": {"field": "headings", "type": "ordinal", "title": "Headings in the note",
          "sort": ["0","1","2","3","4","5","6","7","8","9","10","11","12","13+"]},
    "y": {"field": "notes", "type": "quantitative", "title": "Notes"}
  }
}

Only 89 notes, sixteen percent, carry six headings or more, and those are the ones an outline can usefully serve. This is the single measurement that most constrains the page’s furniture, because an apparatus sized for the long note is dead weight on the common one.

The other constraints are ratios rather than distributions. There are 2,303 resolved links among 537 subject notes, so lateral movement is frequent and a note’s neighbourhood is large: the most connected note has 36 inbound and 49 outbound links. There are 288 tags, the largest covering 240 notes, which makes a tag a coarse filter rather than a category. Frontmatter sources ranges from nothing to 66 entries on one note, so provenance cannot be rendered as a fixed-size element.

What four independent designs agreed on

Four points recurred across designs that had no sight of each other.

An alphabetical list of 554 notes is not navigation. Three of the four dropped resident navigation entirely and summoned search with a keystroke; the fourth kept a rail but filled it with the note’s own outline rather than with the vault’s contents. The reasoning was the same in each case: a flat list of 554 items encodes nothing a reader wants to know, and its length is not the problem — its lack of order is.

A note’s kind is a word, and usually a sentence. Every design rejected colour-coded type chips, independently and on the same two grounds: nine colours are not learnable, and colour alone fails in greyscale. Three went further and glossed the type in place, so a page reads “synthesis — a conclusion this vault asserts” rather than showing a label that assumes the reader has internalised Wiki type system.

Claim-level citations belong beside the claim. Two designs set footnotes as sidenotes in the margin and kept the note-level sources inventory at the foot of the page, deriving spatially the distinction that Linking and citation conventions draws in prose. Neither was told the distinction mattered. A third rejected sidenotes for a stated reason — 124 notes carry footnotes, and full citations set beside the prose would outweigh it — which is disagreement about the cost, not about the encoding.

The link graph is not a navigation surface. Two designs rejected a force-directed view explicitly, on the ground that 2,303 edges render as a hairball and answer no question a reader actually asks. This does not bear on Graphs, which exists to show the vault’s shape rather than to move around it.

Structure is shown continuously, and named on demand. A and D both keep a minimal persistent indicator of the note’s shape and summon a labelled outline over it, differing only in which axis they use: A runs a four-pixel segmented rule across the top of the page, D runs a vertical track down the left gutter. Both size each segment by the length of the section it stands for, so the reader sees position, remaining length, and whether the next section is long, without a list of names occupying the page. The two answer different questions and neither substitutes for the other: a proportional track answers where the reader is, and a named list answers how to reach a section they have in mind.

Where they disagreed

Question A B C D
Outline A segmented rule across the top, expanded on demand A permanent left rail A permanent left rail, also listing end matter A vertical spine in the gutter, plus a summoned overlay
Connections After the prose A permanent right rail At the foot At the foot, named by argument direction
Provenance After the prose; author concluded it wants its own page Right rail, split archived and external At the foot At the note’s boundary
Type and status Gloss sentence plus a six-cell metadata grid A compact single line Gloss sentence; apparatus scaled to warranty Gloss as a callout under the title
Colour Warm paper, restrained Warm paper, dense Monochrome by construction Warm paper, per-type accents

The disagreement about where the apparatus goes is really a disagreement about how often it is wanted. A and D assume traversal is punctuated and put the apparatus at the ends of the reading; B assumes it is continuous and pays two columns for it; C assumes it depends on the note and shows more of it when the note is less trustworthy.

Decisions

Adopted:

  • Figures may exceed the measure. Tables and diagrams take the full width while prose stays at its measure, as in A. Eighty-three notes carry tables and 29 carry Mermaid diagrams, and the comparisons among them are frequently too wide for a reading column.
  • Footnotes render as sidenotes, beside the sentence they support, with the sources inventory kept separate. This is A’s treatment and it encodes a distinction the wiki already makes.
  • D’s visual system, including its callout treatment, its type scale, and its per-type accents.
  • D’s section spine in the left gutter rather than a rail of section names, with a labelled outline summoned over it. Each segment is grown by the length of the section it stands for and flagged as current or passed while the reader scrolls.
  • A running head in the top bar, revealing the note’s identity once the title has scrolled away and naming the section the reader is in.
  • A landmark ribbon at the far left, carrying the wiki’s fixed destinations rather than its contents.

The spine settles an argument the measurements above could not. A rail of section names costs a column whether or not a note has sections, which is the objection the distribution raises; the answer that a centred reading column leaves that space unused anyway is true but concedes the column. A spine costs about 28 pixels, so the 194 notes with no headings pay almost nothing, and it carries what a list of names cannot — relative section length and position in the whole. It also has a narrow-viewport form, turning horizontal and sticky with the section named in words, where a left rail has only collapse. The ribbon and the spine share the left edge between them, which is roughly a third of what the rail would have taken.

Taking the spine costs one scroll handler rather than three features. In D a single pass flags the current segment, advances the progress indicator, and writes the running head, so the breadcrumb and the shape indicator are one mechanism.

Proposed and unsettled:

  • Give the spine a real label affordance. D carries section names in title attributes, which produces a slow unstyled tooltip that no keyboard reaches and no touch device shows, and the spine is unusable without labels.
  • Decide how deep the spine reads. It maps h2 only, and the vault’s long notes carry h3 and h4 beneath them — ten case studies sit under one heading in Case for privacy and security alone.
  • Decide whether the landmark ribbon shows labels. Icons for Graphs, Tags, and Log have no learnable form, and the first exploration already concluded that a note’s kind needs more than one channel.
  • Decide the treatment of the note’s tail. Connections, provenance, the model-contribution chart, and the local graph are four unrelated things stacked in a heap, and a flat list of 66 sources is indefensible. A tabbed region is the current proposal.

Two implementation hazards follow from tabbing anything. Section wikilinks and footnote references resolve to anchors, so a target inside a collapsed panel has to open its panel before scrolling, or the link silently lands nowhere. And content inside a hidden panel leaves the browser’s own find, which matters more on a long note than it first appears.

What the explorations did not settle

None of the four designs was tested with a reader, and each says so in its own opening block. The untested parts are the ones that carry the most weight: whether search ranking behaves on the real corpus rather than on a sample, whether hover previews help or irritate in a link-dense paragraph, and whether a marginal rule reads as “this rests on evidence” without a legend explaining that it does.

The prototypes also assume a desktop reading posture throughout. Three of the four collapse their margin below roughly 1,100 pixels, and what happens to a sidenote at that point — whether it becomes an interruption in the paragraph or disappears behind a control — is the least examined decision in the set.

Built on 5 sources (5 archived here).

Working out connections…