Lemonfiber
← The specification

Plain-language layer & in-product help

Rendered from spec at76d46f3 (2026-10-25) · its source · Edit this page

Status: Accepted · Audience: Both · Area: G — Cross-cutting UX

Purpose

Make the product comprehensible to someone who doesn’t already know the domain.

This ecosystem’s vocabulary is a wall. Indexer, NZB, hardlink, retention, Torznab, custom format, root folder, killswitch, ratio — all load-bearing, none guessable. Existing documentation defines them by reference to each other, so understanding requires already understanding.

The non-technical operator can follow instructions; what they cannot do is infer. Every unexplained term is a point at which they must go elsewhere, and each such point loses some of them.

Behaviour

Explanation lives where the term is used

Not in a glossary they must know to consult. A term appearing in the interface carries its explanation inline — expandable, adjacent, and phrased for someone encountering it for the first time.

Explanations state purpose, not definition

Instead of Say
“An indexer is a searchable index of Usenet articles” “Indexers are search engines that find what you’re looking for. You need at least one; most cost a small yearly fee.”
“Hardlinks allow multiple directory entries to reference one inode” “Lets a file appear in two places while taking up space once — so importing is instant and doesn’t use extra disk.”
“Retention is the period articles remain available” “How far back your Usenet provider keeps things. Longer retention means older content is still downloadable.”

The second column answers why should I care, which is the actual question.

Consistent terms, always

One concept, one word, everywhere. The ecosystem uses grab, snatch and fetch interchangeably; lemonfiber picks one and never varies. Synonyms are a tax paid by the least confident reader.

Numbers are contextualised

“2.4 GB” means little on its own. “2.4 GB — about 40 minutes on your connection” is actionable. Sizes, durations and rates carry consequence where it’s knowable.

Jargon appears alongside plain language, not instead of it

The plain phrasing must not prevent an operator from learning the real term — they’ll need it to search for help. Both are shown, with the plain one leading.

A translated screen keeps the words that are also names

The section above is about a term an operator will search for. A second language puts the same argument under more pressure, because it offers a translator a word that fits the sentence and names nothing.

A form here is a group of services that start and stop together. Dutch has an ordinary word that a dictionary gives for form — and it means a form somebody fills in, which is a different object entirely. An operator reading it has been handed a word that appears in no compose file, no subcommand and no page of the documentation they would search the moment the screen stops being enough.

So a locale translates the sentence and not the name in it. The distinction is not between English and other languages: it is between text and labels. Text is for reading, and every locale is entitled to its own. A label is a thing an operator will meet again somewhere this product does not control — in a filename, in a log line, in a command they type — and those places have one spelling. Renaming it in one surface leaves them holding two names for one thing and nothing that says they are the same thing.

Which words those are is a decision, not an observation, so it is written down rather than inferred. A name added to the product without being declared here is a name a translator will reasonably translate.

Depth is available, never mandatory

A short explanation with an optional longer one. The newcomer isn’t buried and the curious aren’t stonewalled.

A member is never shown the machine

The household watches films; the operator runs the machine that serves them. A member’s surface speaks only about what they asked for, what they can watch and what they can do next. Where an operator reads the disk is full, a member reads that there is no room for new things right now. Where an operator reads a size, a member reads what it means for their allowance. The domain term, its explanation and the figure all stay on the operator’s side, and the stack itself is the house (G2-R16).

So the commitments above are the operator’s. Each concept has one term per audience: the operator’s on an operator’s surface, the household’s on a member’s (G2-R3).

Errors are the highest-value place for this

An error is read by someone who is stuck, and often anxious. It’s where jargon does the most damage and clarity the most good. G4 governs the structure; this feature governs the words.

On the companion

Three of this feature’s commitments become requirements on the app, because a small screen is where each is cheapest to drop (N15).

Depth is available, never mandatory becomes N15-R3: a word the glossary carries is explainable where it is used, with the short form in place and the longer one available without leading. A phone invites choosing one — bury the newcomer, or stonewall the curious — and the requirement is that neither is chosen.

Jargon appears alongside plain language becomes N15-R4, with something the app makes possible: what a word is also called is not only shown but searchable. An operator reaching for the real term is usually reaching for it in order to look something up, and a synonym that cannot be typed into the app’s own search has been displayed rather than given.

Consistent terms, always becomes a prohibition rather than an aspiration. N15-R9 forbids the app defining a word the glossary does not carry, and forbids substituting its own term for one the vocabulary gives. A surface built separately is exactly where grab, snatch and fetch come back, and the tax this feature refuses to charge gets charged after all.

A glossary that could not be read is told apart from idle (N15-R10).

States

Per term or concept:

State Meaning
explained Inline explanation available wherever it appears
contextualised Explanation adapts to the operator’s configuration
deep Extended explanation available on request
untranslated Domain term with no plain-language form yet — a defect

Edge cases

Situation Behaviour
Term has no good plain-language form Explain by consequence rather than definition. Some concepts are only definable by what they cause.
Explanation would be misleadingly simple Prefer accurate-and-longer over simple-and-wrong. Simplification that produces a false mental model costs more than it saves.
Experienced operator finds it patronising Explanations are collapsed by default once acknowledged, and can be turned off wholesale.
Term differs between services State the mapping. Sonarr and SABnzbd use different words for the same thing.
Message would be very long inline Lead with one sentence; link to depth.
Non-English operator Out of scope for 1.0; write text that translates cleanly — avoid idiom and cultural reference.
Explanation drifts from behaviour Explanations live beside the behaviour they describe so they version together.
Household-facing text Seerr and Jellyfin own the wording of their own screens. What lemonfiber itself says to the household follows G2-R16, wherever it is shown.
A name that is also an ordinary word in another language Declare it. A translator handed form will write the word their dictionary gives, and that word names something else.

Acceptance criteria

ID Requirement
G2-R1 On an operator’s surface, domain terms MUST carry an inline explanation wherever they appear. A member’s surface shows none (G2-R16).
G2-R2 Explanations MUST state purpose and consequence, not formal definition.
G2-R3 One concept MUST use one term consistently across all surfaces and messages for each audience: the operator’s term on an operator’s surface, and the household’s on a member’s surface (G2-R16).
G2-R4 On an operator’s surface, sizes, durations and rates MUST be contextualised where the consequence is knowable. A member’s surface states the consequence in place of the figure (G2-R16).
G2-R5 On an operator’s surface, plain language MUST accompany the domain term, not replace it. On a member’s surface, household words replace it (G2-R16).
G2-R6 Extended explanation MUST be available on request and MUST NOT be mandatory.
G2-R7 Explanations MUST be dismissible and disableable.
G2-R8 An explanation MUST NOT explain by resemblance, and MUST NOT talk a cost away.
G2-R9 Where services use different terms for one concept, the mapping MUST be stated.
G2-R10 Error messages MUST follow the same plain-language rules.
G2-R11 Text MUST avoid idiom and cultural reference so it translates cleanly.
G2-R12 Explanations MUST be versioned alongside the behaviour they describe.
G2-R13 Every acronym in shipped text MUST resolve to a glossary entry, or to a word declared ordinary and carrying the reason it is.
G2-R14 The names lemonfiber gives its own things — the words that also name a file, a command or an argument — MUST be declared, and every locale MUST render a declared name as declared and translate only the text around it.
G2-R15 On every surface, the label of a control, a tab, a menu item or a section heading MUST name what it opens or does in at most three words and MUST NOT be a sentence; a sentence MAY explain beside it, and a name declared under G2-R14 counts as one word.
G2-R16 A member’s surface MUST NOT show a service’s name, a domain term, a size, a rate, an address, a version, a stage of the pipeline, or how the stack stands, and MUST say what it says in household words, leading with what the member can do. Where it names the stack it MUST call it the house. A member’s surface is any screen drawn for a household member’s session on any surface, any notification sent to a member, and any text lemonfiber places where the household asks for things.

Two of these are stated as properties, and why

G2-R8 and G2-R13 used to name the harm rather than the rule. A simplification “that produces a false mental model” and a term “treated as a defect” are both true things to want and neither is a property of a build: the first asks whether a sentence leaves a reader with a wrong picture, which nothing but a reader can answer, and the second describes how a team should regard a class of bug rather than what the product must be. Both would have sat unsatisfiable for ever, and a requirement no gate can read is one that quietly stops being enforced.

They now name what is checkable, and the checks exist: explanation by resemblance and cost-dismissal are refused across every glossary entry, and every acronym in every shipped string literal must resolve to the glossary or to a declared ordinary word carrying its reason.

What is deliberately not claimed by either: whether a picture is false is still a question for review, and lower-case jargon is still not enforced. A list of known jargon words would force no decision — a new word simply would not be on it — so the honest position is that the acronym rule is what a gate can hold and the rest is what a reviewer must.