1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
|
# Documentation strategy and philosophy detail
Detail for: guide philosophy, prescriptive vs. descriptive writing, timeless
documentation, future features, citing other sources, and related reference
material. Source: developers.google.com/style (Philosophy, Prescriptive
documentation, Timeless documentation, Document future features, Citing other
sources).
## Philosophy of the guide
- The guide codifies a house style; it is about **internal consistency**, not
objective correctness. It doesn't claim to be an industry standard and
doesn't replace another style guide you already follow.
- Prefer conciseness: rules are stated without lengthy rationale unless the
rationale matters (accessibility, localization).
- When a rule here and a rule in the live guide disagree, the live guide wins.
## Prescriptive (opinionated) writing
Prescriptive documentation recommends a path instead of listing options. When
you're telling the reader what to do:
- **must** = required; **can** = optional; **might** = possible. Avoid
**should** (ambiguous — readers can't tell if it's required).
- Use imperatives for required steps; "We recommend..." for suggestions.
- Describe states precisely: is the state actual or required? Is the outcome
expected or possible?
- Structure the doc around the recommended path: purpose-first headings,
scenarios and examples for the most relevant use cases, commands that work
for the common case.
## Timeless documentation
Document the current version of the product; avoid words that anchor text to a
point in time or assume knowledge of prior/future versions:
- Avoid: *now, new, currently, latest, recently, soon, yet, formerly, was
previously known as*.
- "These subcommands let you interact with HTTP load balancing" — not "These
**new** subcommands...".
- Don't describe how the product changed from previous versions unless the
migration matters; don't describe how it will change.
- Exception: time-sensitive content (blog posts, release notes) can use these;
product docs should not.
## Future features
- Don't use future tense to describe how a feature will work after a future
release or update. Write current, factual behavior.
- If a feature is genuinely upcoming and you must mention it, mark it clearly
and keep the description minimal ("coming soon" style labels are a product
decision, not prose).
- Don't promise availability or dates.
## Citing other sources
- When explaining a concept, define it in your own words, then (optionally)
link for more detail.
- Recommended: "recovery point objective (RPO), which is the maximum
acceptable length of time during which data might be lost..."
- Not recommended: quoting a dictionary/encyclopedia definition with a URL.
- Avoid copying third-party content (docs, websites, books, blogs, images,
Wikipedia, open source docs, GitHub content) unless you're sure you own or
have rights to the assets. When in doubt, don't copy.
- Link to third-party standards and software documentation rather than
re-documenting them.
## When to use this file
Consult this file when writing proposals, design docs, changelogs, or
opinionated guides — the prescriptive/timeless guidance applies most there.
For chat messages and code comments, the core rules in SKILL.md are enough.
|
