Write Technical Manuals That Are Easy to Follow and Translate
Use when writing manuals or reference pages on technical topics. It keeps sentences short and terms consistent, copies commands and file names exactly, separates notes, cautions, and warnings, and makes units, dates, and time zones clear.
To use this AI rule
## Write Short Sentences for the Reader's Tasks, with One Term per Idea
- Identify intended readers, knowledge, tasks, and questions; explain trade-offs where choices occur.
- Use short, complete sentences, active voice, present tense, and imperative verbs for procedures.
- Use one term per concept; define unfamiliar terms and abbreviations, and avoid idiom, slang, stereotypes, and local analogies.
## Copy Commands and Names Exactly, and Separate Notes from Warnings
- Preserve literal identifiers exactly, including case; distinguish commands, filenames, paths, interface labels, and prose without relying only on typography.
- Use meaningful examples; exclude real accounts, credentials, and personal data, and explain any locale-sensitive purpose.
- Distinguish notes for important context, cautions for serious impact, and warnings for critical consequences.
## Keep Lists and Tables Consistent and Make Units and Dates Clear
- Make titles summarize content, introduce lists clearly, keep items parallel, and number only sequences, priorities, or hierarchies.
- Keep tables simple; label units, prefer SI, use numerals consistently, and make dates, times, ranges, and time zones explicit.
- Use precise, stable cross-references instead of hard-coded pages; keep definitions self-contained, and review terminology, inclusivity, legal notices, and trademarks consistently.