# Documentation Guidelines

Guidelines for maintaining tdx documentation, specifically for release notes.

## Release Notes

Release notes in `docs/guide/releases.md` are read by **non-technical users** — analysts, marketers, and business users of Treasure AI and Studio. Write for that audience. Assume no knowledge of package names, build systems, SDKs, or source layout.

### Include

- New commands, options, or features users can invoke
- Bug fixes that affect user behavior or output
- Breaking changes requiring user action
- Noticeable performance improvements
- Deprecation warnings


### Exclude

- Internal refactoring or code organization
- Test coverage improvements
- Implementation details (parameter names, internal APIs, class names, package names, native binaries, build/packaging mechanics)
- Code quality improvements
- Debug logging changes
- Dependency updates (unless they fix user-visible bugs)
- Internal business decisions (pricing changes, cost structure, internal strategy)


### Categories

- **New Features** - New capabilities
- **Breaking Changes** - Requires user action
- **Bug Fixes** - Fixes to existing functionality
- **Performance** - Noticeable speed improvements
- **Improvements** - Enhancements to existing features
- **Deprecations** - Features being phased out


### Writing Style

- Keep each item tight: a bold title (the command, flag, or behavior) followed by a single sentence explaining the user-visible effect. Add a second sentence only when the user needs it to act — e.g., a workaround, a migration step, or the reason for a breaking change.
- Lead with what the user sees or does, not the code path that changed
- Explain the impact on user experience in plain language
- Avoid technical jargon, package names, file paths, and internal implementation details
- Prefer "Studio" / "the installed app" / "chat" over `@anthropic-ai/claude-agent-sdk`, `node_modules`, `codesign`, etc.
- If you can't describe a fix without naming an internal package or build step, it probably belongs in the commit message, not the release notes


### Validation

Would a non-technical end user:

1. Notice this change?
2. Understand what changed in their experience, without looking anything up?
3. Care about this information?


If any answer is "no", remove or rewrite the entry.