Write the direct answer first
A reader and a retrieval system both benefit when a section begins with the answer, then gives conditions, steps, examples, and links. Avoid forcing the key fact to emerge from a long narrative.
Make context explicit
- AudienceState which role, plan, product, location, or customer the guidance applies to.
- VersionName the relevant product or policy version.
- PrerequisitesList what must already be true before the steps begin.
- Stop conditionsDescribe when the reader should not continue.
- Owner and dateRecord who maintains the source and when it was last reviewed.
Use consistent terminology
Choose one primary term for each concept and add known synonyms in the text. If “workspace,” “account,” and “organization” refer to different things, define them. Retrieval cannot repair terminology that the source uses inconsistently.
Prefer stable, meaningful links
Use descriptive link text and a stable canonical destination. If you want an agent to recommend a link, make the URL and its purpose explicit in the approved content. Check for redirects and broken destinations.
Test documentation through questions
Ask the questions a novice, expert, frustrated user, and out-of-date user would ask. If the answer requires guessing, improve the documentation before compensating with a longer agent instruction.