Write Short Help Pages That Show a Command's Most Useful Examples

## Check for an Existing Page, Then Pick the Folder for the Right System Search all source and translated page trees for the command before creating anything. If a page exists, edit it instead of creating a duplicate. If it does not exist, determine where the documented syntax actually works. - Put a command in the common directory only when the same syntax works on at least two platforms. - Put a command that works on one platform in that platform's directory. - Keep English pages in the primary page tree and translations in locale-specific trees with the same platform path. - Use lowercase filenames unless a platform-specific policy requires the command's canonical casing in the page title or invocation. Do not choose a directory from the command's reputation or name. Verify its supported platforms and syntax first. ## Keep the Page Short, with the Title and Description Before the Examples Write each page as a small Markdown reference with this fixed sequence: 1. One H1 whose command name matches the filename, ignoring case where the repository allows it. 2. A blockquoted description, preferably one or two lines. 3. A required “More information” line containing an angle-bracketed upstream URL. 4. Practical examples, each with an imperative bullet description followed by a separate inline-code command line. 5. A trailing newline at the end of the file. Use five examples as the default and never exceed eight. Keep a blank line between the description and command and between examples. Do not use bold, italics, or decorative Markdown in page content. ## Choose Examples for the Most Common Real Tasks Select examples that solve the most common real tasks. Write descriptions in the imperative mood: “List files,” not “Lists files.” Keep them short and action-oriented, and do not explain general operating-system concepts. Verify every example against the command's manual, built-in help, or official documentation. Preserve the documented spacing between options and arguments; use `--option arg` unless the command explicitly requires another form. Place “Display help” and “Display version” as the final two examples, in that order, when those invocations exist. They are lower-priority examples, so omit one when a more useful practical example is needed and the page limit would be exceeded. ## Mark the Parts Users Replace with Double Braces Wrap replaceable values in double braces. Use semantic placeholder shapes consistently: - `{{path/to/file}}`, `{{path/to/directory}}`, and `{{filename}}` for filesystem inputs; - `{{file1 file2 ...}}` for multiple arguments; - `{{option1|option2}}` for alternatives; - `{{1..5}}` for numeric ranges and `{{*.ext}}` for wildcard patterns; - `{{[-v|--verbose]}}` for equivalent short and long options; - `{{[-it|--interactive --tty]}}` for grouped flags. When both short and long forms exist, show both. Never invent a short form: version flags and other common options vary by command. Do not nest placeholders or substitute single braces and square brackets for the required double-brace syntax. Use angle brackets for keypresses: `<a>`, `<Enter>`, `<Space>`, `<Ctrl>`, `<Alt>`, and `<Shift>`. Write combinations with a space, such as `<Ctrl c>`, and sequences as adjacent groups, such as `<Esc><u>`. ## Link to the Official Manual After Checking the Link Works Every page must link to more information. Prefer the command's official manual, project documentation, maintained manual-page service, or platform vendor documentation. Before accepting a link, follow redirects and confirm that the final response is successful. Do not rely on a URL that merely looks plausible. Keep the angle-bracket link on the dedicated “More information” line and avoid promotional or unofficial sources when a primary source exists. Use the same authoritative sources to confirm command names, option forms, argument spacing, platform behavior, help syntax, and version syntax. ## Write Paths and Variables the Way Windows and Other Systems Expect For Windows command pages, keep filenames lowercase unless repository policy says otherwise, but preserve the command's canonical casing in the H1 and examples. Use backslashes in path placeholders. Write environment variables in the syntax of the documented shell: `%VARIABLE%` for the traditional command interpreter and `$Env:VARIABLE` for PowerShell. Examples intended for PowerShell must work in both the oldest supported edition and the current edition unless the page declares a narrower requirement. For other platforms, follow their native path, shell, environment-variable, and option conventions. A shared page is valid only when the shown command syntax is genuinely portable. ## Make Pages for a Command's Other Names and Its Sub-Commands Create alias pages with the repository's alias helper when one exists. State that the command is an alias, link to upstream information, and provide one example that opens the original command's reference page. Keep translated alias pages synchronized through the same helper rather than editing their generated structure independently. For commands with subcommands, mention representative subcommands in the parent description when they have separate pages. Give each documented subcommand its own hyphenated page and include an example that opens the relevant subcommand reference. Do not overload the parent page with detailed subcommand workflows that belong in their own pages. ## Translate a Page Without Changing Its Commands or Layout Translate only after the English page exists. Keep the same example structure, platform path, commands, and placeholders. Leave reserved example domains unchanged and keep placeholder words in the source language when repository policy requires it. Apply locale-specific writing rules instead of mechanically copying English grammar. For example: - Chinese separates Latin text and numbers from Chinese text with spaces and uses full-width punctuation. - French uses third-person example descriptions and a space before required punctuation. - Spanish uses third-person descriptions and preferred localized technical terms. - Brazilian and European Portuguese use third-person descriptions. - Indonesian uses the concise command-description form without unnecessary verbal prefixes. Validate the translated page with the same structural checks as the English source. ## Check the Page with the Checking Tool Before a Person Reviews It Run the repository's page linter on the changed file before requesting human review. Use a full-tree lint only when the change or repository policy requires it. Review the page for: - matching title and filename; - short blockquoted description and a valid information link; - five preferred and no more than eight examples; - imperative descriptions and correct blank lines; - verified option forms and double-brace placeholders; - correct platform directory and native syntax; - help and version examples in the final positions when included; - no decorative formatting; - locale-specific rules for translations; - a final newline. Use the repository's maintenance scripts for mechanical title, link, alias, cross-reference, and command updates when available. Prefer dry-run mode before a broad scripted change. ## Give the AI the Command's Manual and Similar Pages Before It Writes Reduce AI cost and correction cycles by supplying evidence before drafting. Include the command's help or manual output, point to two or three similar approved pages, and provide the page template instead of asking the agent to recall conventions. Check for an existing page first. Batch related page requests when they share context, but review each page independently. Draft five or six high-value examples rather than filling the eight-example limit. Run the linter before human review so formatting errors do not consume reviewer attention. Cost saving must come from better inputs, reuse, and deterministic validation, never from skipping source verification or lowering page quality.