# Technical Writing Guide

> Use when structuring or rewriting standalone technical explanations, reports, status updates, documentation, recommendations, or operational handoffs so readers see the outcome, decision, action, or status first. Triggers on bottom line up front, BLUF, outcome-first writing, inverted-pyramid structure, concise technical prose, executive summaries, caveat placement, or requests to lead with the answer, even when the user doesn't say 'technical writing'.

- Skill: `xonovex/technical-writing-guide` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add xonovex/technical-writing-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xonovex/technical-writing-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: xonovex (https://skillmd.com/u/xonovex)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xonovex/technical-writing-guide

---


# 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](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](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](references/outcome-first.md)
- **Preserve technical precision** - Keep exact identifiers, conditions, units, and comparison bases, see [references/technical-precision.md](references/technical-precision.md)

## Gotchas

- Do not add a visible `BLUF` label 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](references/outcome-first.md) - Load when choosing the lead, ordering evidence and caveats, or writing under uncertainty
- Read [references/technical-precision.md](references/technical-precision.md) - Load when preserving identifiers, conditions, units, comparisons, or technical constraints