summaryrefslogtreecommitdiff
path: root/skills/google-style-guide/reference/strategy.md
diff options
context:
space:
mode:
Diffstat (limited to 'skills/google-style-guide/reference/strategy.md')
-rw-r--r--skills/google-style-guide/reference/strategy.md72
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