Structure principles
- State one document purpose in the opening paragraph and use a single H1.
- Divide topics with H2 and H3 without skipping heading levels.
- Separate rules, facts, examples, and exceptions into distinct sections or lists.
- Replace vague references such as “the above” with exact files, paths, commands, and targets.
Code and data
- Put code in fenced blocks and label the language.
- Use tables for comparison; break long explanations into headings and lists.
- Give links meaningful source text and date time-sensitive facts.
- Instruction docs should include scope, constraints, verification commands, and completion criteria.
Name the beginning and end of the context
State the repository, product, and version the document governs. Separate authoritative sources from areas that must not be guessed. A single retrieved chunk should still make references such as “current” or “that file” understandable.
Useful examples include outcomes and exceptions
- Show the file or output that proves a command succeeded.
- Separate invalid input and the conditions that should stop the task.
- Date time-sensitive values and link the source used to verify them.
- Never put real secrets or personal information in an example.
Final review
Use MD.SAVE’s outline and local Document check for heading flow, internal links, image descriptions, raw HTML, and unclosed code fences.