technical-writing

Files (3)

• LICENSE
• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Technical writing

Help the reader understand, decide, or act with the least unnecessary reading. Preserve technical meaning and the author’s intent. Follow explicit user preferences and project conventions before these defaults. Match the requested language; use American English spelling for English content unless the project uses another variant.

## Establish the task

Infer the audience, purpose, and artifact from the request and existing material. Ask only when missing information would change the substance or audience level. Do not start a mandatory interview.

For revisions, read the whole passage being changed and enough surrounding text to preserve meaning. For factual additions, inspect the relevant implementation or authoritative documentation. Investigate named gaps, not the entire repository. Stop when the requested claims and instructions have adequate support, or identify the specific unresolved fact.

## Write directly

- Lead with the answer, behavior, decision, or task. Put background after the reader knows why it matters.
- Use active voice to identify responsibility. Use passive voice when the actor is unknown or irrelevant.
- Address the reader as “you” in instructions. Name the system or module when describing its behavior. Do not change personal or team statements into second person mechanically.
- Sound like a knowledgeable colleague: friendly, direct, and respectful. Remove promotional claims, jargon without purpose, cultural references, and filler introductions.
- Do not describe a reader’s task as easy, obvious, or trivial. Explain the action instead.
- Keep each paragraph on one idea and connect sentences naturally. Shorten wording without producing choppy fragments or removing necessary explanations.
- Use one term for one concept. Explain unfamiliar abbreviations on first use; preserve literal identifiers and established domain terminology.
- Distinguish requirements, recommendations, and options. Use “must” for requirements, “recommend” for advice, and “can” for capability. Preserve real uncertainty and conditions; do not turn a proposal into a guarantee.

## Organize for use

Use sentence-case headings that describe the content. Skip headings for a short answer. Use bullets for parallel items, numbers for ordered actions, and tables for comparisons that benefit from aligned fields. Avoid deep nesting.

For procedures, establish prerequisites before the steps. Put the condition and location before the action. Give each meaningful action a step, mark optional steps with “Optional:”, and state results after actions when readers need them to proceed. Introduce commands by their purpose. Explain placeholders and show expected output when it helps verify success. Prefer one accessible, direct procedure; separate alternatives only when readers need to choose.

Use code formatting for identifiers, filenames, commands, and literal values. Use bold for visible UI labels. Preserve exact spelling and case. Use descriptive link text, meaningful image alternatives, and unambiguous dates and units. Do not rely solely on color or screen position to convey instructions. Follow the output format’s supported markup and project conventions.

## Adapt to the artifact

These are local working defaults, not mandatory Google templates. Include only what serves the request:

- **Technical explanation or update:** outcome, reason or evidence, practical implication, and next action if one exists.
- **README or how-to:** purpose, prerequisites, shortest working path, and success check. Link to detailed reference rather than duplicating it.
- **API reference:** behavior, inputs, outputs, errors, and a representative example supported by the implementation.
- **Design document or ADR:** problem and constraints, decision, rationale, consequences, and unresolved choices. Separate proposed behavior from implemented behavior.
- **PR description:** concrete problem, resulting behavior, and actual validation. Describe the final change without recounting the conversation.
- **Runbook:** trigger, prerequisites, actions, success signals, and recovery or escalation for relevant failures. Put destructive consequences before the affected step.

Preserve repository templates. Use the appropriate document, presentation, spreadsheet, or PDF skill when creating those file formats; this skill governs their prose, not rendering.

## Verify and deliver

Check the draft against its sources. Preserve negations, scope, versions, defaults, units, error behavior, and requirement strength. Do not invent test results, benchmarks, guarantees, commands, or links. Distinguish illustrative examples from observed output. Flag unverified claims precisely instead of adding a generic disclaimer.

Verify examples through safe, authorized checks or inspection. Do not execute destructive instructions merely to validate documentation. Never include real secrets in examples.

Make one focused editorial pass for repetition, ambiguous references, inconsistent terms, broken structure, and missing prerequisites. Stop when the reader can accomplish the stated purpose and remaining factual gaps are explicit. Do not add a review report unless requested.

Return the requested prose or artifact first. For an edit, briefly identify consequential changes or unresolved facts. Creating text does not authorize sending messages, publishing, or modifying unrelated files.

## Sources and targeted lookup

Adapted in original wording from the Google developer documentation style guide, consulted September 7, 2026. Artifact patterns and verification workflow are local additions. This is an independent skill, not a Google endorsement. The guide’s content is offered under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

The defaults above are sufficient for ordinary work. For an unresolved editorial question, consult the relevant page instead of rereading the entire guide:

- [About the guide](https://developers.google.com/style): project precedence and reasoned exceptions.
- [Highlights](https://developers.google.com/style/highlights): general conventions and links to accessibility, global audiences, and terminology guidance.
- [Voice and tone](https://developers.google.com/style/tone): conversational technical prose.
- [Procedures](https://developers.google.com/style/procedures): task instructions and action order.
- [Text-formatting summary](https://developers.google.com/style/text-formatting): code and UI typography.

Use style sources to settle editorial questions, not to establish product behavior.

From gafar123/the-simple-lazy-developer, MIT.

More from gafar123/the-simple-lazy-developer