Commit Graph
1 Commits
Author SHA1 Message Date
Miranda LimonczenkoandNik Richers 8fa75be01b docs: add a standalone style guide (#50742)
Part 1 of 3. Stack: #50742 → #50744 → #50743.

## Problem

We have several problems:
- Style guidance lives in lots of places and need consolidation
- Our CONTRIBUTING guide has turned into one massive style document that
needs to be broken up



## Solution

Add `apps/docs/style-guide/` as plain markdown. 

| File | Covers |
| --- | --- |
| `README.md` | What the guide covers, who it's for, how to contribute,
and the references it defers to |
| `WORD_LIST.md` | Terminology, spelling, capitalization, and the
`agent` / `LLM` / `AI` distinction. Moved from `apps/docs/` with history
intact |
| `01-voice-and-tone.md` | Audience, brevity, sentence construction |
| `02-elements.md` | Which component renders each piece, and linking
conventions |
| `03-page-structure.md` | Document types, information types, grouping,
chunking, timeless documentation |

### New content

This guide is mostly rearrangement and glue, but it includes some new
content:
- Links and cross-reference formatting
- WORD_LIST entries for LLM and AI agent
- Timeless documentation guidance
- Accessibility guidance
- Sharper guidance on brevity and chunking

## Manual testing

1. Open `apps/docs/style-guide/` on this branch and confirm `README.md`
renders below the file list.
2. Follow every link in `README.md` and read the document through.
3. You can test by locally pointing an agent at the style-guide and
seeing that it makes great choices when revising a document.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Added a documentation style guide covering voice and tone, page
structure, and guidance for writing procedures, code, tables, diagrams,
media, and links.
* Added a word list with preferred spelling, capitalization, and usage,
including guidance on inclusive and concise language.
* Added recommendations for reviewing documentation drafts and runnable
examples.
* Replaced the existing word list page’s content with a link to its new
location in the style guide.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Nik Richers <nik@validmind.ai>
2026-09-25 20:04:52 -07:00