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:
- Notice this change?
- Understand what changed in their experience, without looking anything up?
- Care about this information?
If any answer is "no", remove or rewrite the entry.