Writing Style and Templates
Writing guide for Ryvra documentation pages, including the standard page template and the natural-language-first rules used in IA v2.
#Standard template
- Purpose
- Audience
- Prerequisites
- In plain English
- Step-by-step
- Troubleshooting
- Related pages
- Metadata footer (Last updated + Compatibility window)
- Source of truth
#Writing rules
- Use short paragraphs and action-oriented headings.
- Use concise purpose-first section intros and remove repetitive helper subtext.
- Reduce acronyms or define them the first time they appear.
- Explain concepts before introducing protocol terms.
- Link to deep specs instead of front-loading jargon into overview pages.
- Use consistent terminology across users, merchants, developers, tokenomics, and security pages.
#FAQ authoring
- Add audience tags to each FAQ entry so readers can see who the answer is primarily for.
- Answer in natural language first, then link back to architecture, governance, provenance, or tokenomics deep dives.
- Keep source-of-truth FAQ content in `lib/docs.ts` and update editorial mirrors under `content/` when applicable.
#Collapsible list conventions
- All docs list items render as collapsible `<details>/<summary>` UI in the portal.
- Write summary lines that remain clear when collapsed.
Use nested children for supporting detail
- Move examples, exceptions, or secondary notes under nested children instead of making the top line too long.
- Preserve code examples inside structured `code` blocks when a list item needs inline reference material.
- Do not depend on collapsible behavior to hide critical disclosures that should also appear in surrounding prose.