technical-writing

Applies Diátaxis, Google style, STE, and Global English rules to technical documentation.

Updated Sep 23, 2026
One-click install
npx skills add https://github.com/lucasheriques/pstack --skill technical-writing-lucasheriques
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: technical-writing
Source: https://github.com/lucasheriques/pstack/tree/main/skills/technical-writing
Command: npx skills add https://github.com/lucasheriques/pstack --skill technical-writing-lucasheriques

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Technical docs, RFCs, READMEs, PR descriptions, and commit messages often read as ambiguous, jargon-heavy, or machine-written. This Skill applies four layered writing standards so a tired engineer understands the text on the first read. ## Core Features & Use Cases - Diátaxis mode selection: Classifies each document as tutorial, how-to, reference, or explanation and enforces the rules of that mode without mixing them. - Sentence-level standards: Applies Google developer style (second person, active voice, condition-before-instruction), STE rules (one thought per sentence, consistent verbs), and Global English (no ambiguous pronouns, slashes, or double readings). - Use Case: You draft a README section explaining a CI budget check. The Skill rewrites vague prose like "configuration is performed via budget.json" into concrete statements with real symbol names, one instruction per sentence, and no words that do no work. ## Quick Start Ask the AI to review and rewrite the attached documentation draft using the technical-writing standard.

Frequently Asked Questions about technical-writing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write technical documentation that engineers understand on the first read?▼

Apply four layers: pick one Diátaxis mode per document, address the reader as "you" in present tense, keep one thought per sentence under about 25 words, and remove any phrasing that allows two readings. Cut every word that does no work.

What is the Diátaxis framework for documentation?▼

Diátaxis splits docs into four modes: tutorials (learning by doing), how-tos (steps to a goal), reference (facts for lookup), and explanation (understanding and why). Two questions pick the mode: action versus understanding, and learning versus work. Never mix modes in one document.

How do I choose between a tutorial and a how-to guide?▼

Tutorials serve learning through doing, so every step produces a visible result and you write as "we". How-tos serve work, assume competence, skip teaching, and name the guide by the task, like "How to calibrate the radar array".

Does this writing standard apply to PR descriptions and commit messages?▼

Yes. Every layer except Diátaxis applies to PR bodies and commit messages. A PR body is a briefing readable in under a minute; link swarm logs, SHA lists, and metric tables instead of pasting them.

When should I not use these technical writing rules?▼

Product UI strings are not documentation, so use your product's copy guidelines for those. Also, when a rule makes a sentence worse, fix the sentence another way or leave it alone; the rules serve the reader.