--- name: documentation-writing description: Guidance for durable evergreen documentation and change-oriented framing when a document explicitly needs change history. --- # Documentation Writing ## Use This Skill When Use this skill when writing or reviewing standalone documentation, including READMEs, docs pages, runbooks, architecture notes, user-facing help, and agent guidance. Default to evergreen documentation unless the target document explicitly needs change history. ## Evergreen Documentation Evergreen docs answer: "How does this work?" Write in present tense. Describe the system as it works today. Explain rationale as design intent. The reader should not need release history to understand the doc. Avoid chronology words unless history is operationally relevant: - `new` - `now` - `previously` - `before` - `after` - `changed` - `no longer` Instead of: ```md The worker now retries no-data checks. Previously, dates could become final too early. ``` Use: ```md The worker retries no-data checks within the rolling window because source data can appear after an initial empty response. ``` ## Change-Oriented Documentation Use change-oriented framing only when the target document explicitly needs change history, such as release notes, changelogs, migration notes, PR summaries, deployment announcements, or incident follow-ups. Change-oriented docs answer: "What changed?" They may use words like `new`, `now`, `previously`, `before`, and `after` when those words help explain the delta from earlier behavior. Do not use change-oriented framing in durable docs unless the prior behavior is operationally relevant. ## Scope Boundaries This skill covers standalone documentation. It does not define house style for inline code comments, docstrings, changelogs, release notes, migration guides, incident reports, or GitHub issues yet. When asked to write one of those excluded document types, follow the repo's existing conventions or ask for direction instead of inventing a house style.