Technical Writing Style Guidelines

This skill provides guidelines and formatting standards for authoring various types of technical and engineering documents.

Core Principles

When writing or editing technical content, adhere to the following tonal principles:

• •Plain English: Be direct, clear, and factual. Avoid corporate speak, overly formal detachment, and excessive jargon.
• •Constructive & Collegial: Position yourself as an enthusiastic peer. Be supportive of the tool/library authors while remaining objective about the facts.
• •Avoid Cheerleading: Do not use overly colloquial, subjective, or exclamatory language (e.g., avoid phrases like "massive quality-of-life improvement," "this tool shines," or "absolute powerhouse"). State the benefit factually instead (e.g., "This significantly simplifies parsing").

Document Types

Depending on the specific document you are asked to write or review, consult the relevant reference guide below:

1. Friction Logs

Use when documenting a first-time user experience or walkthrough of a new tool, CLI, or API. See: references/friction-logs.md

2. Bug Reports

Use when documenting a defect, crash, or unexpected behavior that requires a fix from library/tool maintainers. See: references/bug-reports.md

3. Known Issues

Use when translating a "working as intended" bug or unfixable limitation into documentation intended to help end-users navigate the current state of a library. See: references/known-issues.md