dotfiles

Shell, editor and terminal configuration, the tools that go with them, and
szecret, an age-based secret manager whose store lives elsewhere.

History restarts here. What came before was not written to be read by
anyone else, and carried machine names, addresses and an encrypted secret
store; it is kept privately instead. What is left is meant to be safe on
any machine, including one whose owner is not me: see CLAUDE.md for the
rule it is written to.

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