product-writing

Product Writing

Help the reader understand what is happening and what they can do next.

Work from the task

Use only the sections relevant to the requested copy. Preserve the user's meaning, terminology, audience, and requested format. Follow existing product conventions where they help readers recognize controls, commands, and states. A wording task does not itself authorize changes to product behavior or a reorganization of the documentation.

Ground behavioral claims in supplied facts, the relevant implementation or specification, or an observed result. When a fact cannot be verified, identify that uncertainty where it matters and complete the parts that are supported. Do not invent behavior or a cause to make the text sound complete.

Interface copy, errors, and help

• Name the action or state accurately. Distinguish saving a setting from testing a connection, accepting a request from completing a job, and partial success from full success. For example, a queued export should not announce that a file is ready to download.
• Make recovery useful. Identify what failed and the relevant input or operation. Include a next step when it is known and actionable. An unknown network failure does not establish that credentials are wrong. Put detail in the message, an expanded view, or a specific help link as the interface allows; an error need not fill a fixed template.
• Preserve meaningful distinctions. Keep prerequisites, limits, and consequences that affect the reader's decision. Use the product's names for controls and commands. Do not shorten away which item an action affects or imply that an irreversible action is temporary.

Status and diagnostic output

• Describe the state the label promises. Effective settings account for runtime overrides; stored settings should be identified as such. If only the API key comes from the environment, label that field rather than the entire endpoint as environment-provided.
• Keep failure visible. Distinguish unknown or unavailable values from empty, missing, or default values. If partial results are supported, identify what could not be checked. Follow the project's failure behavior instead of introducing a fallback merely to produce a message.
• Preserve output contracts. Keep prose and decoration out of JSON, TSV, and other machine formats. Use existing diagnostic channels for explanations. Keep paths, IDs, and commands complete where users need to copy them, subject to the product's redaction rules.
• Give diagnostic views distinct jobs. When a dedicated inspection command already provides all values and origins, a health summary can focus on deviations, failures, and their sources, with a pointer to full details. Without that separate view, preserve the values needed to investigate the problem. Fifteen normal field: origin rows can bury the two overrides that matter, but removing the only available configuration view loses information. Re-read adjacent labels to catch duplication such as default (default).