# 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.