Write reStructuredText Tech Docs with Real Examples and Check the Build

## Explain What Readers Need and Leave Deep Internals to the Code Write for readers who need to understand and use the documented behavior. Explain concepts clearly and as concisely as possible. Include low-level details when they help a reader make a decision, but leave very deep implementation internals to the source code. - Describe a method signature only when the signature is critical to using the method correctly. - Document the command arguments and options that affect the main workflow, not every available switch. - Do not restate an error or exception when its in-code message already explains the cause and remedy. - Prefer a focused explanation, a realistic example, and a link to related detail over an exhaustive catalog. ## Pick the Branch from the Change Type and Release Info Never hard-code the list of maintained versions. Read the project's authoritative release metadata before choosing a target branch, then apply the change-type rules consistently. - Bug fixes target the oldest maintained branch that contains the bug. - New-feature documentation targets the branch that introduced the feature. If that branch is no longer maintained, use the next maintained branch. - Typos, rewording, restructuring, and other non-feature changes target the oldest maintained branch. - Documentation for independently versioned subprojects follows its own declared policy; when specified, route every change to the oldest maintained branch, including new features. Record the change type and the maintenance data used for the decision. If the release metadata is unavailable or ambiguous, do not guess the branch. ## Keep Heading Marks and Line Wrapping the Same Use underline characters consistently for heading levels: equals signs for level 1, hyphens for level 2, tildes for level 3, periods for level 4, and double quotes for level 5. Each underline must span the full heading text length. Apply any path-specific heading exception declared by the repository. Wrap prose at 80 characters except for tables, URLs, and orphan lines where wrapping would reduce readability. Keep list bullets at the beginning of the line. Do not split bold or italic spans across lines. For inline code, use paired double backticks. For language-default code examples, use the concise double-colon form unless the marker would appear alone on its line. Use an explicit code-block directive when the language or rendering context must be named. ## Indent Directives and Write Links the Same Way Indent directive content by four spaces. Leave a blank line after a double-colon marker before its content, and leave blank lines before and after each directive. Align continuation lines in a multi-line list item with the start of the item text. Use the standard admonition that matches the message: note, tip, warning, caution, or seealso. Use dedicated version-added and deprecated directives with the relevant version and a short explanation. Use absolute document paths for internal document links. Use a labeled cross-reference when linking to a specific section. Never use a relative internal path. For external sites, place named link targets at the bottom of the file instead of embedding inline URLs in prose. Use the documentation system's dedicated roles for language API classes, methods, functions, and built-in types. ## Show YAML, XML, and Other Config Examples in a Fixed Order When a feature supports multiple configuration formats, show all supported formats in a configuration-block directive. Keep a repository-wide order so readers can compare pages without relearning the layout. - For services and general configuration, use YAML, XML, then the programming-language format. - For routing, validation, and object mapping, use attributes, YAML, XML, then the programming-language format. - For translation resources, use XML, YAML, then the programming-language format. Use ordinary tabs only for parallel content that is not configuration, such as alternative tools or workflows. When examples differ between framework-integrated and standalone applications, use distinct language identifiers so the renderer and reader can tell the contexts apart. ## Write Code Examples with Real Names and a File-Name Comment Follow the target language's coding standards and the project's established best practices. Use realistic names and scenarios rather than placeholder words that hide intent. Use reserved example domains and the repository's conventional sample vendor name. - Wrap code-block lines at 85 characters where practical. - Indent examples by four spaces, including YAML. - Include namespace and import declarations when they help the example run or clarify types. - Start a code block with a comment naming the file; do not add a blank line unless the next line is also a comment. - Prefix every shell command with a prompt marker. - Use the language-appropriate comment form when folding omitted blocks. - Use a bare ellipsis when shortening part of a value on the same line. - Preserve format-specific spacing rules, including spaces inside YAML inline mappings when required. An example should teach the supported path without pretending to be production-complete. Do not omit a prerequisite that would make the shown code fail. ## Write Plain American English and Avoid Words Like “Simply” Write in American English. Use title case for section headings: capitalize the first and last words and major words, while leaving short closed-class words lowercase unless they begin the title. Address the reader as “you” instead of speaking as “we.” Use gender-neutral pronouns. Prefer active voice, basic vocabulary, and direct sentences that work for an international audience. Contractions are acceptable. Do not use an Oxford comma. Avoid idioms and belittling words such as “obviously,” “simply,” “just,” “easy,” “clearly,” “trivial,” and “of course.” These words can hide missing explanation and discourage readers. Every image needs concise alt text that starts with a capital letter and ends with a period. Do not begin with “A screenshot of” or “Diagram of.” Explain complex diagrams in surrounding prose rather than forcing all detail into alt text. ## Build the Docs Locally and Check Warnings and Broken Links Write directories with a trailing slash and file extensions with a leading dot. Use a neutral sample project root such as `your-project/` in directory trees. Keep filenames, paths, commands, and reference targets consistent across prose and examples. Before considering a documentation change complete: 1. Install the documentation build dependencies in the designated build workspace. 2. Run the repository's documented build command. 3. Serve the generated output locally when visual inspection is needed. 4. Check changed pages for warnings, broken references, malformed directives, code rendering, heading hierarchy, and image descriptions. 5. Confirm that the selected target branch still matches the change type and current maintenance metadata. Do not report success from source inspection alone when the repository provides a local documentation build.