206. Reference: pages people land on

The reader has arrived at the fourth setting on the page. They have not read the introduction, and the introduction has no realistic prospect of negotiating a return visit. The setting needs to make sense where it stands.

Reference writing supports that kind of arrival. It identifies the object, states its behavior and limits, and gives the reader a route to the next needed answer. It can contain a developed explanation, but it should not require an appointment with the whole manual before answering one question.

Orient a direct arrival

Use a title that identifies the term, feature or contract. Preserve the exact interface name where that name is the lookup target. Add the product, version or platform when the distinction matters.

The opening should establish what kind of thing the reader has found and the relationship that makes it useful. A Vexy Lines mask and a FontLab mask layer share a word; their definitions need enough product context to prevent one from answering the other's question.

Supply local context at important sections too. A deep link can land beneath the opening. A parameter's meaning should not depend on an unexplained it whose owner appeared three headings earlier.

Orientation need not repeat a full concept lesson. State the relevant object and scope, then answer. Link to deeper explanation when readers need it.

Define the distinction behind the name

A definition that repeats the label leaves the work undone. “A clone creates a clone” may be difficult to dispute, but it offers little help in choosing one.

Find the distinguishing relationship. What is shared, independent, stored, calculated, displayed or changed? What nearby object might the reader mistake for this one?

For the archived Vexy Lines clone example, the useful distinction is a continuing link to some source properties alongside independent rendering attributes. Changes to pattern direction or spacing in the source affect the clone; color, dashes and image threshold are shown as independently variable. That is richer information than a general promise of creative flexibility.

An explanatory definition can therefore develop the relationship:

A Vexy Lines fill clone follows its source's pattern changes while retaining independent rendering choices. The linked fills can share the pattern without having to look identical.

This example paraphrases the inspected source model. It does not establish a current menu label, all supported fill types, or every independent property. Those details belong in the applicable version's reference when verified.

The glossary has a 100-word ceiling and no minimum. A reference page can be longer when the subject requires it. A brief definition needs no padding to become respectable.

State the contract at the right scope

Decide what the page promises to cover: one command, one group of controls, an API operation, a format, or a concept's reference details. Completeness follows that declared scope.

An exact list of supported values must be complete for its stated version. A teaching excerpt can be partial if it says so. Do not present a selected list as exhaustive or infer that omitted items are unsupported.

Likewise, an observed list in a source may be stale or use an older label. The clone source names particular fill types and distinguishes cloning from the copy behavior of other types. A current reference must check both the names and that fallback behavior. Silently replacing an unfamiliar name with a more familiar one would hide the question instead of answering it.

Include the information the reader needs to use the contract: conditions, accepted inputs, effects, results, limits and relevant failures. Do not turn completeness into a requirement to repeat every neighboring page.

Choose tables for comparison and lookup

A table helps when several items need the same fields. Prose helps when the reader needs a relationship developed in order. Use both when the page needs both jobs done.

Choose columns that expose the relevant distinction. A parameter table may need name, purpose, unit, range and default. A mode comparison may need condition, behavior and consequence. An API reference may need input, output and error semantics.

Avoid a table whose descriptions simply repeat its names. “Contrast: controls contrast” is a heading that has found a second home in a cell.

Keep one meaning per column. If a cell is unknown, say Not specified in a working reference or resolve the gap before publication. Do not let a dash mean zero, unsupported, unchanged and unknown in different rows.

A table can be concise without demanding a verb in every cell. Column headers may already establish the relationship. What matters is whether the row tells the reader something they can use.

Give numbers their conditions

Values need units, ranges and defaults when the product specifies them. Preserve whether a boundary is inclusive, whether zero has a special meaning, and whether a default applies only to new objects.

A current value may have been remembered from the previous session. It is not necessarily the factory default. A preset is not automatically a universal recommendation. A qualitative setting may need a description of the visible change rather than an invented numeric starting point.

Direction of effect also needs care. A spacing value may have a useful monotonic relationship; an angle is cyclic. “Higher is stronger” is not a general rule for controls with numbers beside them.

For an output setting, relate advice to the actual delivery requirements and product model. The words print and screen alone do not establish a universal resolution. State the verified relationship and preserve the variables the reader must supply.

Worked reference: a bounded numeric setting

This fictional proof application supplies the following contract:

• Preview scale accepts whole-number percentages from 25 through 200.
• New views start at 100%.
• Existing views retain their stored value when reopened.
• The setting changes display size, not the saved proof's dimensions.
• The packet does not specify handling of out-of-range input.

A usable reference is:

Preview scale

Preview scale changes the proof's displayed size. It leaves the saved proof's dimensions unchanged.

Property	Value
Unit	Percent
Accepted values	Whole numbers from 25% through 200%, inclusive
New-view default	100%
Reopened view	Uses its stored scale
Saved proof dimensions	Unchanged

A reopened view at 75% has not contradicted the new-view default. It is showing the value that view retained. The distinction belongs in the reference because it answers the apparent inconsistency without making the reader investigate it.

The missing out-of-range behavior remains a review question. The reference must not claim that the application clamps, rejects or rounds an invalid value until that behavior is established.

Keep a useful example small enough for its job

A reference example should resolve a lookup question. It may show one input and result, demonstrate a boundary, or contrast two settings. It need not begin with creating a new project unless that setup is part of the question.

For the fictional scale contract, an example can compare a new view with a reopened one. It does not need a tour of export, sharing or account creation. The compact case earns its space by explaining the default's scope.

If an example grows into a sequence of dependent choices, consider a linked procedure. There is no fixed action count at which an example changes genre; the test is whether it still answers the reference question or has taken on a separate task.

Use real names and inputs when they clarify the mechanism, while identifying fictional data. Keep code samples executable only when their runtime, API and result have been verified. Otherwise use labelled pseudocode or prose.

Put limitations next to what they limit

A capability and its consequential boundary belong close enough to be read together. A reader should not have to reach the final notes to learn that the opening promise excludes their case.

State the product version, mode, platform or input that governs the limit. Distinguish unsupported behavior from unknown behavior and unsupported configurations from configurations known not to work.

Keep uncertainty when it is part of the evidence. May, usually and in this case can carry real scope. Removing them does not complete a fact check. When the source is merely vague, research the condition rather than polishing the vagueness into certainty.

An experimental label also needs context. Explain the actual limitation or support boundary the source supplies; do not attach a generic warning to a stable feature simply because its mechanism is complicated.

Let the explanation retain a human voice

Reference prose can be clear and companionable without adding a benefit slogan after every table. It shows consideration by noticing the question a value or condition will raise.

In the scale example, the reopened view supplies a small puzzle and the stored value resolves it. The explanation has movement. It does not need to call the feature powerful or the experience seamless.

Use a concrete distinction and connected sentences. A longer sentence can carry the condition; a shorter sentence can state its consequence. Keep literal identifiers stable while varying the prose around them.

A generic sentence about enhancing work usually adds little. Replace it with a supported consequence if the reader needs one. Otherwise end the section. A reference entry is allowed to finish when it has answered the question.

Link to the next question

Choose related links by the work the reader may need next: a prerequisite concept, a procedure using the feature, a collaborating setting, or recovery from a documented failure.

There is no mandatory quota. A short entry may need one useful link; a large reference may need several groups. Organize a substantial set so readers can choose rather than inspect a list of vaguely related nouns.

Write link text that predicts the destination and remains useful out of context. It need not exactly duplicate the destination title when an action phrase is clearer, but it must not imply a different feature or promise an answer the page does not contain.

Check that the target exists and that it answers the intended question. File existence, anchor validity and semantic relevance are separate checks. A page can pass the first and still send the reader to the wrong explanation.

Make the opening useful outside the page

A search result or quoted passage may carry only part of the opening. Name the product, term and central distinction early enough to survive that separation. Avoid a pronoun whose referent exists only in the title or previous page.

Do not design around a supposedly fixed snippet length. Search systems and presentation contexts vary. Write a coherent opening that stands on its own, then inspect important actual entry routes where available.

Reader vocabulary can bridge to official terminology. The page may mention a common search phrase and then give the exact term. That helps discovery without renaming the control in the instructions.

For colliding terms, a short disambiguation page can route readers to the appropriate product. It should explain enough of each meaning to support the choice. It cannot guarantee that every search or assistant will preserve the boundary, so the destination still needs its own context.

Maintain one authoritative account

Keep the full contract in its maintained location. Task pages can repeat the subset needed to complete their task and link for the rest. Shared controls may have one explanation that other pages reference.

Some repetition is necessary for independent entry and safe action. The aim is to avoid unowned copies that drift, not to make every page depend on a chain of links for basic context.

Record provenance privately: the source, version, observed behavior, exact strings and unresolved conflicts. Public prose should show relevant scope and limits without exposing the entire editorial worksheet.

When sources conflict, establish whether they describe different versions, platforms or states. If the behavior remains unresolved, do not choose the sentence that reads most smoothly. A confident paraphrase can preserve an error with impressive efficiency.

Keep current reference and release history distinct

A reference describes its declared version or maintained behavior. Release notes record what changed in a particular release. Link between them without silently rewriting history.

A short version note can help someone identify a newly introduced feature or changed default. Use it when the distinction matters; adding “new” to every page creates another maintenance task whose deadline nobody remembers.

A rename note belongs where older terminology still affects the reader's route. Preserve necessary historical names and maintain redirects or search aliases where the publishing system supports them. Do not let old names remain as accidental current labels.

Review the page as a lookup

Choose questions the page claims to answer: the default, a range boundary, the meaning of a mode, a version difference or a failure condition. Locate each answer without reading the page from the beginning.

Then read the explanation continuously. Tables and headings should support lookup without leaving the relationships between facts unintelligible.

Inspect the rendered page for table headings, line wrapping, exact identifiers, links and important conditions. Compare the facts with the source contract. A passing build does not establish that the default is correct or that a link answers the right question.

Practice: change the packet, then the reference

Use the fictional scale packet. Write a compact entry and one paragraph explaining why a reopened view can differ from the new-view default. Try a version that begins with the apparent discrepancy and one that begins with the storage rule. Choose the order that best serves the reader's question.

One possible opening is: “The view reopens at 75%, although the default says 100%. Both values have a job: one belongs to this view, the other to a new view.” The apparent contradiction gives the paragraph movement; the explanation resolves it without changing either number.

For the second pass, remove the persistence fact. The table must stop promising stored values, and the explanatory paragraph must change with it. Leave the unknown visible in review rather than inventing a restart rule.

Next supply a new fact: invalid values are rejected with the exact message “Enter a whole number from 25 to 200.” Add the error contract without changing the range or inventing automatic correction. An exact error string is part of the reference even if the writer would have phrased it differently.

Checklist

• Direct arrivals can identify the product, term and applicable scope.
• The definition explains the distinguishing relationship.
• The page's declared contract is complete or its teaching limits are explicit.
• Tables preserve units, ranges, defaults and unknowns.
• Examples answer a specific lookup without absorbing another task.
• Consequential limits sit beside the capability they qualify.
• Prose develops useful relationships without generic praise.
• Links answer identifiable next questions and reach the intended targets.
• Shared facts have a maintained home and necessary local context.
• Version notes preserve the difference between current reference and history.
• Review checks actual lookup questions and the rendered presentation.