xonovex Technical Writing Guidelines
Structure technical prose so the reader sees what matters before the supporting detail.
Plain prose mechanics are owned by writing-guide. Load it with this skill and apply its clarity, terminology, evidence, and concision rules throughout the document.
Essentials
- Lead with the reader's need - Put the outcome, decision, action, answer, or current status first, see references/outcome-first.md
- Order by consequence - Follow the lead with implications, decisive caveats, evidence, and background in descending importance, see references/outcome-first.md
- State uncertainty honestly - Lead with what is known, what remains unknown, and what evidence or decision comes next, see references/outcome-first.md
- Preserve technical precision - Keep exact identifiers, conditions, units, and comparison bases, see references/technical-precision.md
Gotchas
- Do not add a visible
BLUFlabel unless the requested format requires one. The opening sentence carries the bottom line. - Outcome-first writing does not remove evidence or caveats. Keep a caveat beside the lead when it can change the conclusion.
- Do not invent a decision, owner, deadline, confidence level, or next action. State the gap when the source does not resolve it.
- A tutorial leads with the reader's task or learning outcome. An incident report leads with impact and current status before chronology.
- A specific artifact skill owns required sections and fields. Apply these ordering rules within that structure.
- Do not call prose ASD-STE100 compliant unless the task applies the full controlled vocabulary and grammar standard.
Progressive Disclosure
- Read references/outcome-first.md - Load when choosing the lead, ordering evidence and caveats, or writing under uncertainty
- Read references/technical-precision.md - Load when preserving identifiers, conditions, units, comparisons, or technical constraints