diff options
Diffstat (limited to 'skills/google-style-guide/reference/strategy.md')
| -rw-r--r-- | skills/google-style-guide/reference/strategy.md | 72 |
1 files changed, 72 insertions, 0 deletions
diff --git a/skills/google-style-guide/reference/strategy.md b/skills/google-style-guide/reference/strategy.md new file mode 100644 index 0000000..eaa0f07 --- /dev/null +++ b/skills/google-style-guide/reference/strategy.md @@ -0,0 +1,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.
\ No newline at end of file |
