Good docs writing

Write docs the way Modal writes them: direct, friendly, confident, and ruthlessly practical. Explain the why in one breath, then show working code. Treat the reader as a capable developer who wants to ship, not a student who needs a lecture.

Read references/style-guide.md for the full rule set (Voice, Structure, Terminology, Punctuation, Code examples, Formatting) and apply every rule while drafting.

The rules that matter most, before you open the reference:

Address the reader as "you", never "the user" or "one".
Open with the concept or benefit in the first sentence. No throat-clearing.
Put a minimal runnable example near the top, then explain what just happened.
Remove every em-dash. Use a period, comma, colon, or parentheses instead.
Cut vague intensifiers ("seamlessly", "powerful", "robust", "cutting-edge"). Show a thing being easy instead of calling it easy.
Backtick every code identifier, command, parameter, path, and filename.

To review existing prose against these rules instead of drafting, use good-docs-audit.

Good docs writing

Read references/style-guide.md for the full rule set (Voice, Structure, Terminology, Punctuation, Code examples, Formatting) and apply every rule while drafting.

The rules that matter most, before you open the reference:

Address the reader as "you", never "the user" or "one".
Open with the concept or benefit in the first sentence. No throat-clearing.
Put a minimal runnable example near the top, then explain what just happened.
Remove every em-dash. Use a period, comma, colon, or parentheses instead.
Cut vague intensifiers ("seamlessly", "powerful", "robust", "cutting-edge"). Show a thing being easy instead of calling it easy.
Backtick every code identifier, command, parameter, path, and filename.

To review existing prose against these rules instead of drafting, use good-docs-audit.

good-docs-writing

让 AI 帮你安装

Good docs writing

链接

创作者

Good docs writing