204. Explaining concepts

A setting can have a clear label and still leave the reader with no useful idea of what will happen when it changes. The label names the handle. The explanation shows what the handle is attached to.

Good concept writing makes a relationship visible. It can begin with a definition, a small puzzle, a comparison or an observed result. It then develops the idea far enough for the reader to recognize the distinction or make the next relevant choice. The point is understanding; a compulsory metaphor would only add another thing to explain.

Find the relationship the reader needs

Before drafting, name the likely misunderstanding. Perhaps the reader thinks that changing a preview saves the source, that a mask deletes hidden material, or that a tool chooses an answer when it only helps inspect alternatives.

Write the supported relationship in plain language. What acts on what? Which state changes? Which state remains separate? What conditions govern the result?

This gives the explanation a center. Without it, a page can accumulate accurate definitions while leaving the original question untouched.

A useful private brief contains the concept, the distinction the reader needs, the evidence, an example, and any candidate comparison with its limit. An empty comparison line is harmless. An empty evidence line needs attention before the page can make the claim.

Choose the kind of help the idea needs

A definition identifies something. A contrast distinguishes it from something nearby. An analogy maps a useful relationship from another domain. A worked example shows the relationship under particular conditions.

These methods can cooperate, but they are not substitutes for one another.

Reader's question	Useful starting form
What does this term mean?	A definition with the distinguishing property
Which of these two things do I need?	A contrast organized by the relevant choice
Why does this behavior occur?	A mechanism followed through an example
How can I picture this unfamiliar relationship?	A bounded analogy or diagram
What should I expect in this case?	A worked example with starting state and result

Start with the simplest form that answers the question. A longer concept page is justified when the relationships depend on one another or the reader needs a developed model. It does not need to apologize for its length by turning its final paragraph into an unnecessary procedure.

Begin with something the reader can inspect

An observable discrepancy can create curiosity without inventing drama. The same image produces lines in one view and dots in another. A selection changes when the active layer changes. A visible result remains unchanged after an operation the reader expected to alter it.

Use such an opening only when the behavior is established or the example is explicitly fictional. Then explain the mechanism that resolves the discrepancy.

The movement can be simple: observation, relationship, consequence. A longer sentence can connect several parts of the mechanism; a short sentence can mark the distinction the reader should keep.

Do not conceal a prerequisite or consequential limitation to preserve suspense. The pleasure belongs in discovering the explanation, not in discovering too late that the instructions did not apply.

Compare analogies while drafting

Trying two candidate analogies can reveal what each assumes. A stencil may help someone picture a drawing region. A clipping-region description may help someone who already knows graphics systems. Neither background can be assumed merely because the person uses a creative application.

Write the literal explanation first. Then compare each candidate against it: which relation transfers, which details do not, and what wrong inference might a reader reasonably make?

Keep the useful comparison in the finished section. A direct explanation with an example may work better than either candidate. The drafting exercise does not require two analogies in the published page.

Avoid sorting people into fixed “visual” and “technical” types. You can offer a diagram, definition and example without making a claim about how each reader learns. The reader gets to use the help that helps.

Map the relation and state the boundary

An analogy should explain a particular relationship. A mood such as magic, power or freedom does not explain a mechanism.

A stencil can help explain the broad role of a Vexy Lines mask: the mask controls where the layer's fills appear. Its transparent areas permit drawing; opaque areas conceal it. The comparison gives the reader a visible division between areas that allow the result and areas that do not.

The card stencil stops being a sufficient model at the edge. The archived Vexy Lines documentation distinguishes normal, sharp and smooth mask behavior: stroke ends may extend slightly beyond the boundary, be cut at it, or become thinner near it. A single hard-edged card cannot teach all three cases.

State that boundary when it becomes relevant. Do not imply that “stencil” alone establishes exact clipping, softness, opacity or every available operation. Those are product facts to explain separately.

The comparison is a way into the model. It is not a replacement specification.

Worked case: separate image, pattern and result

The archived Vexy Lines fill explanation distinguishes pattern paths, an image-derived signal and the rendered strokes. For a patterned fill, these let the writer separate where strokes can run from how their thickness responds to the image.

One analogy is a person shading along planned rows. The route of the hand and the pressure applied along it are different choices. Together they affect the mark. This helps a reader distinguish the pattern from the tonal influence.

The analogy has limits. A person's judgment about where to draw does not establish how a particular fill constructs geometry. Vexy Lines offers different fill families; do not force a tracing or handmade operation into every claim about regular parallel paths.

A direct explanation can therefore do most of the work:

In a patterned fill, the paths establish the geometry along which strokes are rendered. The image supplies tonal information used in that rendering. The resulting strokes are the artwork; the source image supplies information for producing it.

This paragraph distinguishes roles without promising a specific control value, shortcut or export option. An actual tutorial would add those from the applicable product version and verify the visible result.

The useful next question is which part of the model a setting affects. Establish that from its documented behavior. Do not turn the broad model into a universal troubleshooting prescription: a wrong-looking result can have more than one cause.

Worked case: deformation after rendering

The archived Vexy Lines mesh explanation puts deformation after the fills have rendered their strokes. That ordering is the concept worth preserving.

A flexible sheet with a drawing on it can help the reader picture the relation: changing the sheet's shape moves the drawing. The comparison explains spatial deformation of the result. It does not prove the application's internal caching, recalculation strategy or exact geometry.

A developed explanation might read:

The fills produce the strokes first. The mesh then changes their spatial arrangement, much as bending a sheet changes the shape of a drawing on it. The comparison concerns where the marks go; it does not describe a new way to interpret the image's tones.

The ordering gives the paragraph its movement. The final sentence limits the comparison where a reader might extend it too far.

If the page goes on to explain folded visibility, mask pinning or a particular mesh template, obtain the separate behavior for that feature. A flexible-sheet comparison does not establish which side is visible or whether a mask moves with the mesh. The source model must carry those decisions.

Worked case: variable fonts and positions

A variable font contains variation data along one or more axes. An application selects axis values and calculates the corresponding result. Named instances identify particular locations; they need not be the only locations available when the application exposes axis controls.

Keyframes can provide a limited analogy for interpolation between source designs. The familiar relation is that a result can be calculated at a position between specified states. The analogy stops short of making the font an animation or requiring one timeline. Several axes can define a larger design space.

Keep source editing and the exported font distinct. An editor's component controls are not automatically extra axes exposed by the exported variable font. The reader needs the actual mechanism and scope, not every operation suggested by the word variable.

For outline interpolation, explain the relevant correspondence requirements from the product and format documentation. A pleasing transition in an analogy does not prove that source outlines are compatible or that intermediate designs look right. Verification still belongs to the actual outlines and results.

See the variable-font definition for the shared terminology. Use the analogy to make the relationship approachable, then return to those names.

Keep a small concept small

A local control may need one sentence and a comparison image. A named editing mode may need a definition and a distinction from a nearby mode. Giving every setting an elaborate metaphor can make the manual feel like a guided tour whose guide has misplaced the exit.

For example, the glossary describes Power Nudge as distributing a move through more of a contour by adjusting other nodes as well as the selected ones. That may already explain the useful distinction. A fabric analogy could suggest movement spreading beyond the point pulled, but it must not imply a particular falloff or exact shape preservation that the source has not established.

Compare the direct description with the candidate analogy. Keep the extra image only if it resolves a real difficulty. A good sentence need not arrive wearing a comparison.

Gloss a term where the question arises

An unfamiliar term can often be explained within the sentence or in the next one. Give enough meaning for the present task, then link to a longer treatment when it becomes useful.

A gloss might identify a signal as image-derived tonal information or an instance as a result at selected variation coordinates. The needed precision depends on the reader and the surrounding operation.

Avoid announcing the reader's supposed ignorance. “A fancy term for…” dismisses a term that may be useful, while “beginners should know…” makes the explanation about the reader's status. State the meaning and continue.

Do not cram every definition into a parenthesis merely to keep it inline. If the qualification matters, give it a sentence. If several definitions interrupt the same action, the page may need a brief concept section before the procedure.

Make the example teach the central relationship

Choose the smallest example that makes the distinction visible. Establish the starting state, action, result and relevant limit. Use exact UI text when the example is executable; identify fictional or partial examples before readers can mistake them for tested instructions.

For a fictional proof application:

• Preview mode changes how the current proof is displayed.
• Changing the mode does not alter the saved proof.
• The available modes and their exact appearance are not supplied.

An explanation can say:

Changing Preview mode changes the display of the current proof. The saved proof stays the same. The control belongs to how you inspect the work, not to an edit of the saved proof.

The example makes display and stored content distinct. It cannot prescribe a particular mode, promise a comparison layout or invent a saved-file confirmation. Those details remain absent.

An exercise can invite exploration after explaining the expected relationship. “Try it and see” becomes unhelpful when it substitutes for a known mechanism the writer could have stated.

Offer depth without repeating the introduction

A short definition can orient a direct arrival. A paragraph can develop the mechanism and limit. A longer page can connect several relationships or help someone make a consequential choice.

Not every concept needs all three forms. Write the depth the task requires and link between forms when readers need a route. Avoid duplicating a complete explanation on several pages that will later disagree.

A concept page can end when the reader understands the distinction it set out to explain. Sometimes that naturally leads to a procedure. Sometimes a reference link or a clear final consequence is enough. An action sentence is a useful private test when action is the purpose; it is not the only legitimate ending.

Historical context belongs when it changes the reader's understanding of a current constraint or choice. Keep it proportionate. A reader can be curious without having asked for every event that led to the control in front of them.

Give images and prose different jobs

A diagram can reveal relationships that prose would describe slowly. A comparison strip can show how a result changes across values. A screenshot can identify a control in its context.

State what the image demonstrates and which conditions apply. Name important controls in text so the explanation survives a missing image or an alternative presentation. Provide a suitable text alternative and caption for the image's actual job.

A caption such as “Different settings” records almost nothing. A useful caption identifies what varied and what the reader should compare. Avoid adding a cause that the image alone cannot establish.

Choose the image after identifying the concept. The most attractive screenshot may show a side issue while hiding the relationship the page needs to explain.

Check what a reader can now explain

Ask a reader to restate the relationship, distinguish a nearby case, or predict a result that follows from the supplied facts. Listen for the model they formed, not merely whether they repeat the terms.

If the explanation uses a stencil, check whether the reader has inferred a hard edge where the product permits another behavior. If it uses keyframes, check whether they assume a single timeline. The boundary of an analogy is a good place to test comprehension.

A successful response from one reader is evidence about that reading. Record it without claiming universal understanding. A same-writer review can inspect logic and factual scope; it cannot stand in for an independent reader response.

When a misunderstanding appears, locate the sentence or missing condition that allowed it. Add the needed distinction there. More background is not always the remedy.

Practice: explain, compare, then remove a fact

Use the fictional proof packet above. First write the direct explanation. Then try two comparisons, each concerned only with the distinction between viewing and changing the saved object. State the limit of each in your working notes.

For example, trying on a pair of glasses can suggest a changed view of an unchanged object. It can also imply a purely optical process, which this packet does not establish. Keep only the viewing-versus-editing relation if you use it; the comparison supplies no implementation facts.

Choose one comparison or neither. Write a connected paragraph that begins with the visible change and ends at the saved-proof boundary. Vary sentence length where the thought turns. Keep the exact label intact.

Now remove the statement that the saved proof remains unchanged. Revise the paragraph. The analogy must not continue to promise preservation after the source has stopped supplying it.

For a final pass, turn the explanation into a partial procedure. Mark the missing mode choices and expected appearance. This exposes the difference between a concept that can be explained and an operation that can already be taught from start to finish.

Checklist

• The explanation has a specific relationship or distinction to teach.
• Definitions, contrasts, analogies and examples do their appropriate jobs.
• The opening gives the reader a concrete way into the idea.
• Each analogy maps a relation and states the relevant boundary.
• The product model remains separate from the analogy's extra implications.
• Worked examples preserve starting conditions, results and unknowns.
• Exact labels and technical terms remain recognizable.
• Depth follows the reader's question without compulsory forms or quotas.
• Images demonstrate a named relationship and have useful text support.
• The second pass tests a likely misunderstanding as well as factual accuracy.
• Claims about reader understanding match the checks actually performed.