morgankrey
|
dd836fc8b2
|
docs: Add documentation conventions, brand voice guidelines, and gold standards (#49176)
## Summary
This PR establishes the foundation for documentation quality and
automation.
## Documentation Conventions (`docs/.conventions/`)
**CONVENTIONS.md** - Structural guidelines covering:
- What needs documentation vs what to skip
- Page vs section decisions (with examples)
- Document structure and section ordering
- Formatting conventions (code, JSON, tables, callouts)
- Anchor ID patterns for stable deep-linking
- Settings documentation pattern (UI first, then JSON)
- Terminology standards (aligned with docs/AGENTS.md)
- Prettier formatting requirements
**brand-voice/** - Zed's writing style:
- `SKILL.md` - Core voice principles
- `rubric.md` - 8-point scoring criteria (must score 4+ on all)
- `taboo-phrases.md` - Patterns to avoid (exclamation points, hype
words)
- `voice-examples.md` - Before/after transformations
## Gold Standard Examples (`docs/.doc-examples/`)
Four templates demonstrating best practices:
- `simple-feature.md` - Overview/navigation docs
- `complex-feature.md` - Comprehensive feature docs
- `configuration.md` - Settings documentation
- `reference.md` - API/tool reference
## Related
Follow-up PR #49177 applies these conventions to existing documentation.
Release Notes:
- N/A
|
2026-02-14 14:20:03 -06:00 |
|