technical-writing

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

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Technical docs often confuse readers with mixed document types, passive voice, ambiguous sentences, and jargon. This Skill gives you a four-layer standard so any tired engineer understands your docs, RFCs, readmes, PR descriptions, and commit messages on the first read. ## Core Features & Use Cases - Diátaxis mode selection: Classify each document as tutorial, how-to, reference, or explanation, and keep modes from mixing. - Sentence-level rules: Apply Google developer style (active voice, commands, condition-first), STE rules (one instruction per sentence, word limits), and Global English (no ambiguous pronouns, noun strings, or misplaced "only"). - Review checklist: Run an 8-point checklist covering mode purity, command phrasing, word economy, naming consistency, and factual accuracy of symbols and counts. - Use Case: Paste a draft README section and get it rewritten so instructions are commands, conditions come first, real symbol names replace jargon, and every sentence reads one way only. ## Quick Start Ask the AI to review and rewrite your documentation draft using the technical-writing skill's four-layer standard.

Frequently Asked Questions about technical-writing

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

FAQPage Schema
How do I structure technical documentation with Diátaxis?

Diátaxis splits docs into four modes by two questions: does content serve action or understanding, and learning or work. The result is tutorial, how-to, reference, or explanation. Keep each document in one mode and link between them instead of mixing.

How to write clear instructions in developer documentation?

Write instructions as direct commands with the condition first: "To delete the document, click Delete." Use active voice, address the reader as "you", keep one instruction per sentence, and split sentences longer than about 20 words.

What is the difference between a tutorial and a how-to guide?

A tutorial teaches a learner by doing, with visible results at every step and a "we" voice. A how-to solves a specific problem for a competent user, skips teaching, and allows forks like "If you want x, do y."

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

Yes. Every layer except Diátaxis applies to PR descriptions and commit messages: cut dead words, use active commands, keep one thought per sentence, and remove ambiguity. Product UI strings are excluded and follow product copy guidelines instead.

Why should documentation avoid words like simply and easily?

Words like "simply", "easy", and "quickly" in procedures insult readers who are stuck; if it were simple, they would not be reading. Google developer style bans them along with buzzwords, figurative language, and "please" in instructions.