google-dev-docs

Files (2)

• SKILL.md
• REFERENCE.md · references/

SKILL.md (first lines)

# Google Developer Documentation Style

Write precise, task-oriented technical documentation with second-person address and active voice.

## The core rule

**Task-oriented headings, present tense, second person ("you"), active voice.**

Workflow: `state user goal in title` → `prerequisites first` → `numbered steps with concrete code examples` → `verification step`.

## Mechanics

1. **Second person.** Address the developer directly as "you"; avoid "we", "us", or third-person generalities.
2. **Present tense.** Describe current system behavior in present tense ("Returns a 200 OK status", not "Will return").
3. **Task-oriented headings.** Start headings with gerunds or action verbs ("Configuring authentication", not "Authentication overview").
4. **Active voice.** "The server processes the request" rather than "The request is processed by the server".
5. **Code blocks with context.** Every code snippet must include necessary imports, setup, and expected output.
6. **Pronoun clarity.** Ensure "this", "that", and "it" clearly point to a preceding noun.
7. **Consistent terminology.** Use identical terms across guides, API references, and UI labels.
8. **Concise error messages.** Explain what went wrong and how to fix it immediately.

## Verify

- Headings use gerunds or action verbs describing tasks
- Sentences consistently use second person ("you")
- Code snippets are complete, syntactically valid, and tested
- Active voice used throughout instructions
- Present tense used for API descriptions

## Do not

- Use future tense for deterministic software behavior ("The method will return...")
- Leave code snippets without imports or setup context
- Use vague filler phrases ("Simply run...", "Just configure...")
- Mix second person and first person within the same tutorial

## References

For exact mechanical rules (numbers, percentages, ordinals, ranges, abbreviations, units), read `references/REFERENCE.md` when a draft contains any of these — load on demand, not upfront.

## Example transformations

**Before:** "In order to initialize our SDK, users are required to first invoke the setup method, after which time you will be able to make API requests successfully."

**After:** "To initialize the SDK, call `setup()`. Once initialized, you can make API requests."

**Before:** "Simply add the configuration dictionary to your project and you're good to go!"

**After:** "Add the configuration dictionary to your project configuration file."

From surendranb/writing-skills, MIT.

More from surendranb/writing-skills