208. Architecture of help

Imagine a reader who remembers half a setting's name and exactly what went wrong. The help site remembers the complete name and has filed it beneath a heading the reader has never encountered. Both parties possess useful information. The architecture has to arrange a meeting.

A help system connects questions to answers and answers to useful next steps. Some readers follow a tutorial; others arrive at a table row, an error message or an old link. Design for these routes without assuming that everyone reads in sequence or that nobody ever reads an explanation closely.

Organize around recognizable work

Group material by tasks and concepts readers can identify. For a drawing product, that might mean bringing in material, editing it, inspecting results and exporting. For type design, drawing, spacing, variation and font production may provide useful areas.

Use research and product knowledge to choose the actual categories. A tidy sequence imagined by the documentation team may not match how people work. Some tasks cross several areas and need direct routes of their own.

A menu or command index still has a job. Someone who knows the control's name should be able to look it up quickly. Workflow navigation and exact-name reference can coexist; each answers a different question.

Read the top-level headings as a short account of the work the site supports. Then inspect what lies beneath them. A promising category with no usable pages is a sign on an unopened door.

Give learning and lookup their own routes

A newcomer may need a bounded path to a first useful result. A returning reader may need one default value or a forgotten modifier. The same person can need both routes on the same day.

A getting-started path chooses safe material, a supported sequence and a result that teaches something meaningful. It can explain a relationship at the moment it becomes visible. Avoid introducing every option before the first result.

Reference provides the depth the chosen path leaves aside: exact values, conditions, modes and limits within its scope. Link from the learning path when a new question becomes useful, and from reference to the concept or procedure that explains how to use the information.

The distinction is about purpose, not a judgement that beginners need warmth and experts deserve only tables. Both need clear language. Both can appreciate an explanation that has noticed the difficult part.

Give each page a primary job

The main content types provide useful starting contracts:

Type	Reader's purpose	What the page supplies
Concept	Understand a relationship	Explanation, distinctions, examples and limits
Tutorial	Learn through doing	A bounded learning path with safe starting material
How-to	Complete a known task	Supported actions, results and relevant recovery
Reference	Look up a contract	Exact names, values, effects, conditions and scope
Troubleshooting	Investigate an observed problem	Symptom-based checks and supported next actions

A page can contain a short explanation inside a task or an example inside reference. It need not obey a rule of absolute purity. Split material when a second job interrupts the first or deserves a separate address.

The title should predict the primary job. “How masks affect fills” promises an explanation. “Limit a fill to a region” promises a task. A mask settings reference promises lookup. Keep that distinction visible in the body.

Make every arrival intelligible

A reader may enter through search, an in-product link, a shared anchor or a bookmark. Give the destination enough context to establish product, subject, applicable version and relevant prerequisites.

The opening can be brief, but there is no universal sentence count that proves orientation. A complex cross-product page may need a comparison before the reader can choose. A narrow reference entry may need only a precise definition.

At important section anchors, repeat the noun or condition needed for local understanding. Avoid a passage beginning “This also changes them” when the objects are named only on the previous screen.

Provide an alternate route for a predictable wrong arrival. A page about FontLab mask layers can distinguish the Vexy Lines meaning and link to it where that helps. The distinction should explain the choice, not merely offer two product names and hope the reader already knows which one they need.

Write titles that predict the answer

Use the reader's task, a recognizable concept, an exact label or a symptom, according to the page's job. Add the product when a shared term could lead to the wrong interpretation.

A title should carry enough information to choose the page when seen alone. Do not force every title below a word quota or make every title a verb phrase. “Preview scale” can be a good reference title; “Change the preview size” can be a good procedure title.

Keep wordplay out of routes where a reader needs recognition. An article may have an expressive title and a clarifying subtitle. A recovery page should name the problem people are trying to locate.

After drafting, compare the page with its title. If the answer changed, revise the promise or restore the missing content. A working link to the wrong promise still wastes a visit.

Connect pages by the next question

A link should answer a likely question that the current page has raised: “What does this mean?”, “Which value should I use?”, “How do I do that?”, or “What if the result differs?”

Place the link where it becomes useful. Keep essential conditions and short required facts in the current route. Sending someone away to discover a prerequisite can interrupt the task the page claims to support.

Use descriptive text that remains meaningful in a link list. The destination should fulfill that text even when its heading uses a slightly different phrase. Exact title matching is helpful in some cases, not a substitute for semantic agreement.

Choose the number of links by the questions. A short entry may need none; a large feature may need grouped routes. A fixed quota can produce padding or omit a needed destination with equal efficiency.

Start troubleshooting from what is observed

Readers usually know the symptom before the cause. Use exact error text and recognizable descriptions of the observed state. Then guide investigation through questions whose answers can actually be checked.

A product model can help choose checks, but it does not make a symptom prove one cause. Incorrect stroke thickness might involve more than one setting. A file that cannot be found is not necessarily deleted. Keep the distinction between observation, possible explanation and confirmed diagnosis.

Order checks by their relevance, effort and consequence. A cheap observation can be useful before a reset that destroys diagnostic state. Keep any necessary preservation action before a potentially destructive remedy.

When a cause and remedy are established for the reported condition, state them plainly. When they are not, give the next supported check rather than pretending the page knows the answer. A troubleshooting route can end with a clearly identified unresolved state and a supported escalation path.

Build a decision path from evidence

For this fictional help system, the packet contains two checks:

• If the message is “No destination selected,” the user must choose a destination before retrying export.
• If the message is “Access denied,” the cause and remedy are not established.
• These are the only conditions supplied.

A useful entry route is:

Observed message	Supported next step
“No destination selected”	Choose a destination, then retry export
“Access denied”	Preserve the message and investigate the applicable access conditions; no remedy is established by this packet

The second row is not a finished customer recovery guide. It exposes the missing research. Adding “choose another folder” would make the table look symmetrical without making its advice supported.

The architectural lesson is to preserve distinct states. Two errors involving an export destination do not automatically share a cause, a remedy or a safety claim about the source file.

Help search meet the reader's vocabulary

Collect the terms people actually use from available searches, questions and support records. A reader may name a desired result while the product names a mechanism. The page can bridge between them.

Use a common phrase where it naturally explains the subject, then introduce the exact term. Keep interface instructions aligned with the actual label. Search vocabulary should provide a route to the feature, not create several unofficial names for it.

Search results deserve direct inspection. Try exact labels, common task phrases, quoted errors and important old names. Record which page appears and whether it answers the question. Do not claim a ranking improvement simply because a phrase was added to a heading.

The contents, index and in-product links remain useful even when search is a common route. Traffic evidence can inform priorities; an unsupported claim that almost everyone enters through one door cannot.

Give machines the same clear boundaries

An assistant or search system may extract a section without its surrounding page. Product names, version scope, exact strings and explicit relationships help the extracted passage retain meaning.

Where the site provides machine-readable indexes or discovery files, keep them aligned with maintained pages and useful destinations. Their presence alone does not prove that an assistant will retrieve the right page or cite it accurately.

Review actual retrieval or answer examples when that is part of the task. Separate index availability from correct answers. A source passage that distinguishes two products is useful evidence for a system; it is not a guarantee about what the system will do with it.

Connect in-product help to deeper help

A tooltip or contextual help panel can identify a control and its immediate effect. A web page can explain the mechanism, options, examples and limits. Make the transition worth the click.

If a short label uses one name and the destination uses another, determine whether there has been a rename, a locale difference or an accidental inconsistency. Repair the relationship at the appropriate source. Documentation cannot fully compensate for a misleading product label by quietly using a better one.

Keep help links sensitive to the relevant product and version when the system supports that routing. Test them from the state where the reader invokes them. A destination that works in a browser may still be wrong for the selected control.

Preserve old routes deliberately

When a page moves, provide a redirect or other supported route from its old address. When sections change, preserve useful anchors or update their incoming links. Check the final destination, not only the presence of a redirect.

A renamed feature may need aliases and a short migration note. A retired feature may need a historical page explaining its status and any established alternative. A replacement is a fact to verify, not an empty field that the writer must fill.

Keep historical terms where they explain older material. Keep current instructions current. Repeating an old name casually throughout the site can blur the boundary the migration note was meant to establish.

A small route inventory can record the old path, intended new destination, reason and last check. Use it after moves and relevant releases. The reader should not have to know that a page was reorganized to recover their bookmark.

Decide how versions share a page

A single page with explicit version notes can work when the underlying task stays recognizable. Separate versioned pages can be clearer when behavior or routes diverge substantially. Choose according to the actual differences and the maintenance system's capabilities.

A badge alone may not explain whether an older reader can follow the steps. State the applicable behavior or route. Distinguish current reference from the historical account in release notes.

Tie updates to changes in labels, shortcuts, defaults, supported formats and known limitations. Search related examples, screenshots and summaries as well as the main feature page. A corrected paragraph can coexist with an outdated caption if the edit never looks beyond the body text.

Let the structure survive localization

Stable page purposes, explicit terms and descriptive links help another writer preserve the route. Avoid a title whose essential meaning depends on an idiom or joke. An observation inside an explanation can be adapted more freely when its instructional job is clear.

Separate tasks when their routes are genuinely different; do not assume a slash in a title always proves that two pages are needed. A comparison reference may properly cover import and export together, while two procedures may benefit from their own destinations.

Check translated navigation, text expansion, target-language product strings and fallback routes where relevant. Preserve warnings and prerequisites structurally so their importance does not depend on an English tone cue.

Accessibility belongs to the same route review: heading hierarchy, meaningful links, readable tables, text alternatives and usable navigation all affect whether the answer can be reached.

Maintain the map through concrete triggers

Give a page or section a responsible owner and a source of truth. Record the last meaningful verification and the events that should prompt another look.

Useful triggers include a changed label, shortcut, format, support boundary, feature name, repeated question or failed search. Choose a review schedule that fits the product and evidence rather than a universal calendar.

Keep the record small enough to use. Ownership without a trigger can leave a page untouched; a recurring meeting without a changed page can do the same.

When several reports point to one misunderstanding, inspect the shared route. The fix may be a better title, a missing concept, a corrected example or a product change. Do not answer every repeated question with another copy of the same paragraph in a new location.

Test scenarios through the site

Give a reviewer a question and starting point, not the destination page. Include a learning route, a lookup, a troubleshooting case and a shared-term collision when those are relevant to the change.

Record the query or entry link, chosen result, interpretation, next action and point of difficulty. Then test the repair through that route again.

An automated link check can establish that files or anchors exist. A browser check can establish what loads and how navigation behaves. A reader trial can reveal what that reader understood. Report each at its actual scope.

A complete map is more than a table of contents that looks balanced. It is a set of routes that reach the promised answers.

Practice: route one question without expanding its facts

Use the fictional export-message packet. Design a task page, a short error reference and a troubleshooting entry. Write each title and opening, then name the link that connects it to the next useful answer.

Keep “Access denied” unresolved unless more evidence is supplied. The architecture must not hide that gap by routing the reader in a circle between pages that all sound as though another page contains the remedy.

For the prose pass, develop the explanation of one route through a concrete arrival: a reader pastes the exact message into search. Keep this scenario explicitly fictional. Let the paragraph follow the decision to the destination, without inventing a measured search result or reader reaction. For example: “The reader pastes ‘No destination selected’ into search. A page with that message as its heading can confirm the match before explaining the missing choice.” This describes the intended route, not an observed search ranking.

For the second pass, remove the destination-selection remedy from the packet. Update the route and its promises. A link labelled “Fix the export” is now too strong if the target supplies only a description and an unresolved question.

Checklist

• Main categories reflect recognizable work and have usable content beneath them.
• Learning, lookup and recovery have clear, connected routes.
• Each page has a primary job and enough context for direct entry.
• Titles and links predict answers their destinations actually provide.
• Troubleshooting preserves the distinction between symptom, cause and remedy.
• Search vocabulary bridges to exact terminology without renaming controls.
• Machine-readable routes are maintained and their results are not assumed.
• In-product help reaches the right product, version and subject.
• Moves, renames and retirements preserve useful historical routes.
• Localization and accessibility retain the structure of the task.
• Ownership, review triggers and scenario evidence support continued maintenance.