203. Terminology: calling things by their names

A reader looking for reference artwork behind a glyph finds an explanation of a stencil. The word mask is present in both places. Almost everything the reader needs to do is different.

In FontLab, a mask layer can hold a reference drawing. In Vexy Lines, a mask controls where a layer's fills appear. Naming the product resolves more than a vocabulary problem: it gives the reader the right object to imagine.

Terminology lets an explanation remain recognizable as it moves between the screen, the manual, a search result and another language. Stable names give the prose something solid to move around.

Distinguish the label from the idea

A displayed label tells the reader where to look or what to invoke. A concept name tells the reader what kind of thing they are discussing. A search phrase may describe the problem before the reader knows either name.

Keep those roles connected without treating them as interchangeable.

Suppose a fictional application labels a setting Preview scale. A reader might search for “make the preview bigger.” The explanation can use that phrase and then identify Preview scale as the relevant setting. Calling the control “view size” in the next step would make a second name appear where there is only one control.

Write the label exactly when referring to the interface. Use ordinary prose to explain its meaning. The label can be awkward, long or capitalized differently from the surrounding sentence; recognition takes priority over silently improving it.

New labels follow the house's sentence case. Existing labels keep their actual case and meaningful punctuation. These are different jobs for the writer.

Match the object the reader must find

Verify labels against the relevant product, version, platform and language. Record that context when it matters. An old manual or a nearby product can provide a clue without establishing the current string.

Preserve ampersands, spaces, spelling and meaningful ellipses. Put the sentence's own punctuation outside the label. Keep commands and machine-readable names exact even when their casing looks unusual in prose.

Add a control type when it helps: the Name field or the Export button. The generic word is lowercase unless it is part of the displayed name. Avoid adding it when the target is already clear.

For an icon-only control, use its accessible name where available. Appearance and position can supplement the name, but they should not become the only route. A “button on the right” may move when the layout or language changes.

In technical site prose, use the guide's highlight syntax for interface text. Neutral overviews use italics, and plain Markdown without highlight support can use bold. Formatting identifies the role; it does not change the string.

Name containers by their role

A panel can float. A dialog can be modeless. A pane need not be a tab. These facts make the old shortcut of classifying every container by its appearance unreliable.

Use the product's established terminology and explain the behavior relevant to the task.

Term	Useful distinction
Panel	Groups related controls or information; may be docked or floating
Property bar	In FontLab, the contextual strip of controls for the current tool or selection
Window	A distinct application or document surface identified by the product
Dialog	Presents choices, settings or information for an interaction; may be modal or modeless
Pane	A region within a window or container; not necessarily tabbed

If a dialog restricts interaction until dismissed, that behavior may matter to the procedure. Establish it for that dialog instead of deriving it from the word alone.

Contextual controls need their starting state. Identify the selection or active tool before pointing to a property-bar control that appears only in that context. A perfectly spelled label is little help if the reader cannot make it appear.

See the interface glossary for the product-specific entries and the mechanics guide for presentation rules.

Choose verbs for actions and states

An interaction verb tells the reader what to do and, sometimes, what must be true afterward. Prefer the intended state when the physical gesture would leave it ambiguous.

“Click the checkbox” could turn it on or off. “Select the checkbox” states the required result. “Turn on automatic preview” can describe the setting without assuming one input method.

The interface-actions guide provides the full set. The main distinctions are:

• Choose a menu command or option.
• Select or deselect an object, text range, list item or checkbox state.
• Click when a pointer click is the relevant action.
• Press a key; press and hold when it must stay down.
• Tap for a brief touch and touch and hold for sustained contact.
• Type when producing characters with the keyboard matters; enter when another supported method, such as pasting, is also acceptable.
• Drag when movement occurs while the relevant contact or selection is maintained; state the release point when it matters.
• Turn on or turn off an ordinary setting; preserve activate, enable, disable or toggle when it is the exact term or a distinct operation.

These are distinctions to apply, not a claim that every interface permits only one gesture. A command may be available through a menu, shortcut and button. Give the route the task needs and name alternatives when they are useful.

Avoid hit for a key and click on for a control. Use a precise familiar verb instead of making the action sound more vigorous than it is.

Keep key combinations and sequences distinct

Keys pressed together use plus signs. A sequence needs words or punctuation that makes the order clear. A modifier combined with a pointer gesture can be written as Shift-click or Alt-drag when that is the documented action.

Supply the macOS form first and the Windows form in parentheses on first mention when both platforms are in scope. Preserve the actual assignments. Do not assume that replacing Cmd with Ctrl produces the equivalent action.

For a fictional command with those verified assignments:

Press Cmd+E (Ctrl+E on Windows).

The compressed “Cmd/Ctrl+E” obscures the platform distinction. Ctrl is a separate key on a Mac, and its presence is not a request for the reader to substitute Cmd.

Keep Return, Enter and numeric-keypad keys distinct when the product does. State focus, keyboard layout or held-key duration if any affects the action. A letter that invokes a tool while the canvas has focus may enter text in a field.

If sources disagree about an assignment, investigate the version, platform, mode and context. Do not choose the shortcut that makes the sentence more familiar or the comparison table more symmetrical.

Keep shared product nouns from crossing the boundary

The glossary records product scope. The following comparison shows why the scope belongs in the sentence; it is a conceptual map, not a set of complete tool instructions.

Term	FontLab context	Vexy Lines context
Layer	A glyph drawing layer, including master or reference contexts	A document layer holding fills
Mask	A reference drawing in a mask layer	A stencil controlling where layer fills appear
Group	Requires a qualifier, such as kerning group or a specified artwork grouping	A container that bundles layers and can carry a source image
Fill	A tool or treatment affecting which contour regions are filled	A mode that generates artwork from an image
Brush	A drawing tool whose stroke retains a centreline before expansion	A tool for painting masks
Knife	Modes can add nodes, break contours or slice shapes	A tool that inserts points and splits curves in its supported objects
Transform	Can name a numeric transformation panel	Can name the canvas transformation tool

Name the application and, where needed, the mode or object. “Use the Knife” does not tell the reader what the cut will leave. “Edit the group” does not identify whether the subject is kerning, artwork or a collection of layers.

A comparison can be pleasantly concise while preserving the difference:

A FontLab mask layer gives you another drawing to compare. A Vexy Lines mask determines where fills can appear. The shared name does not give them a shared job.

The closing observation follows the explanation. It adds no tool behavior and requires no joke for the distinction to remain clear.

Repeat the name when the reader needs it

Once the product and object are established, the panel, the mask or an unambiguous pronoun can carry the next sentence. You need not repeat a long label as a signature on every line.

Restore the name when another object could be the referent, when the section can be entered directly, or when the sentence is likely to travel by itself in a support reply or search result.

Keep synonyms in their proper role. Reader vocabulary can bridge to a term; it should not become an unannounced alternate label halfway through the procedure. A useful explanation might mention both line spacing and vertical metrics while making their relationship clear. The actual field names still need the correct product context.

Do not invent private abbreviations to relieve repetition. Expand an established abbreviation when the audience needs it, then use it consistently. A shorter string is not a shorter task if the reader has to decode it.

Sentence variety belongs around the name. Change the order of condition and response, develop an example, or give a limit its own sentence. Leave the object recognizable.

Define only what earns its place

A definition should let the reader recognize the concept and distinguish it from nearby ones. State what it is, then add the mechanism, use or boundary that makes the distinction useful.

For a hypothetical review application:

A review set is a saved collection of proofs selected for one review. It records which proofs belong together; it does not record an approval.

The second sentence prevents a plausible misunderstanding. An extra sentence about efficient collaboration would add little unless the evidence establishes a more specific relationship.

The glossary limit is 100 words, with no minimum. Link to a longer explanation when the subject needs it. A local definition can be shorter than the glossary entry because the surrounding task supplies context.

Bold a newly introduced term when that helps readers notice the definition. Do not turn typography into an exact-once ritual that prevents a separately entered section from supplying necessary context. Repeated full definitions may still be redundant; inspect their jobs.

Use the glossary as a record of decisions

Check the preferred name, definition, product scope, aliases, protected strings and status. A proposed translation is not an approved translation. A glossary entry is a maintained editorial record, not proof that a shortcut was tested in the current application.

When a term changes, record why, what replaces it, and which surfaces need review. The published entry should explain the concept; private notes can preserve the research and unresolved questions.

The glossary and the screen may disagree. Identify the relevant version and locale before resolving the disagreement. An exact interface instruction needs the applicable displayed label. A conceptual definition needs the correct meaning. Sometimes both records require a change; sometimes they describe different releases.

Automation can find missing identifiers, unknown term IDs or inconsistent spellings. It cannot establish that two similarly named features do the same thing. That requires product and editorial evidence.

Handle awkward labels and renames deliberately

If the actual interface contains a typo, keep the reader able to find the control and record the product issue. An explanatory note may help when the difference would otherwise confuse. Do not scatter sic through instructions merely to demonstrate that the writer noticed.

If only the source document contains the typo, correct the documentation to match the verified interface. The distinction matters: reproducing an old mistake is no more exact than silently inventing a new label.

A rename requires more than replacing a word in body text. Check titles, links, captions, screenshots, examples, downloads and reused snippets. Keep historical names when they are needed to explain a migration or quote an artifact; do not leave them as current instructions by accident.

A foreign product name found in a page deserves investigation. It might belong to an intentional comparison or an exact quotation. It might also reveal copied material whose neighboring behavior claims need checking. Inspect the context before deleting or substituting it.

Make terminology work across languages

Stable concepts and exact interface strings give translators a usable map. Supply enough context to identify the object, the action and the target locale. Explain whether a name is protected, translated in the product, or awaiting approval.

The surrounding English can remain observant and well paced. Avoid putting a required distinction inside a pun or local idiom. A vivid concrete example may travel well when its role is clear; no example is guaranteed to need no adaptation.

Use target-language product strings when they are established. If the product remains in English, explain the documentation's treatment of its labels. Do not invent a localized button and then ask a reader to find it on an English screen.

Check text expansion, keyboard assignments and context where they affect the instruction. A translated label is part of the target interface, not merely an English word with a dictionary equivalent.

Review names separately from the argument

After the page's structure is settled, collect its labels, identifiers, shortcuts and product terms. Compare them with the appropriate source and glossary entry. Then inspect each occurrence in context.

Search for old names and known variants, but treat a hit as a question. Historical accounts and marked counterexamples may legitimately contain them. Likewise, option or panel may be an entirely clear reference after the full name appears.

Check headings and links. Their wording should make the destination recognizable; it need not be character-for-character identical to the destination title when a clearer action phrase preserves the meaning.

Finally, read the explanation without its formatting. Does the text still make clear which product, object and action it concerns? Highlighting can help the reader see a distinction the words establish. It cannot supply a missing one.

Practice: explain an exact name without replacing it

Use this fictional packet:

• Review set is the displayed name of a collection.
• The collection groups selected proofs for one review.
• Add to set adds selected proofs to that collection.
• Neither operation records approval.
• No shortcut or alternate-language label is supplied.

Write a concept paragraph that begins with the reader's need to keep related proofs together. Introduce the exact name and explain the approval boundary. Then write a short instruction using Add to set without inventing a menu hierarchy.

For the style pass, develop the distinction through one concrete contrast: putting proofs together versus deciding what to do with them. Change the rhythm while keeping the names fixed. The prose can become more fluent without making the collection an approval mechanism.

For the second pass, replace the application with another fictional product whose review set does record approval. Write a comparison that names both products before the shared term. Do not let a compact sentence erase the contradiction you are explaining.

Finally, introduce a supplied label change from Add to set to Add proofs. Update the instruction and its references while preserving the approval boundary. A rename changes the string; it does not, by itself, change what the operation does.

Checklist

• Labels, identifiers and shortcuts match the applicable source exactly.
• Concepts, displayed names and reader search vocabulary remain distinct.
• Container names reflect product roles, not a universal appearance rule.
• Interaction verbs express the intended action or final state.
• Platform, focus and held-key requirements remain explicit where needed.
• Shared nouns identify the product and relevant mode or object.
• Repetition preserves recognition without unnecessary renaming.
• Definitions are useful, bounded and within the glossary's length limit.
• Proposed terms and translations retain their status.
• Renames and source conflicts are investigated across affected surfaces.
• A separate name pass checks the rendered route as well as the draft.