# Lerianstudio Ring Documentation Structure > Documentation Structure - Skill: `tomevault-io/lerianstudio-ring-documentation-structure` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/lerianstudio-ring-documentation-structure` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/lerianstudio-ring-documentation-structure/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/lerianstudio-ring-documentation-structure --- # Documentation Structure Good structure helps users find what they need quickly. Organize content by user tasks and mental models, not by internal system organization. ## Content Hierarchy ``` Documentation/ ├── Welcome/ # Entry point, product overview ├── Getting Started/ # First steps, quick wins ├── Guides/ # Task-oriented documentation │ ├── Understanding X # Conceptual │ ├── Use Cases # Real-world scenarios │ └── Best Practices # Recommendations ├── API Reference/ # Technical reference │ ├── Introduction # API overview │ └── Endpoints/ # Per-resource documentation └── Updates/ # Changelog, versioning ``` --- ## Page Structure Patterns | Page Type | Structure | |-----------|-----------| | **Overview** | Brief description → "In this section you will find:" → Linked list of child pages | | **Conceptual** | Lead paragraph → Key characteristics (bullets) → How it works → Subtopics with `---` dividers → Related concepts | | **Task-Oriented** | Brief context → Prerequisites → Numbered steps → Verification → Next steps | --- ## Section Dividers Use `---` between major sections for visual separation. **When to use:** - Between major topic changes - Before "Related" or "Next steps" sections - After introductory content - Before prerequisites in guides **Don't overuse:** Not every heading needs a divider. --- ## Navigation Patterns | Pattern | Usage | |---------|-------| | Breadcrumb | Show hierarchy: `Guides > Core Entities > Accounts` | | Prev/Next | Connect sequential content: `[Previous: Assets] \| [Next: Portfolios]` | | On-this-page | For long pages, show section links at top | --- ## Information Density **Scannable content:** 1. Lead with key point in each section 2. Use bullet points for 3+ items 3. Use tables for comparing options 4. Use headings every 2-3 paragraphs 5. Bold key terms on first use **Progressive disclosure:** - Essential info (80% of users need) first - Advanced configuration in separate section - Edge cases and rare scenarios last --- ## Tables vs Lists **Use tables when:** Comparing items across same attributes, showing structured data (API fields), displaying options with consistent properties **Use lists when:** Items don't have comparable attributes, sequence matters (steps), items have varying detail levels --- ## Code Examples Placement | Type | When | |------|------| | Inline code | Short references: "Set the `assetCode` field..." | | Code blocks | Complete, runnable examples | **Rules:** 1. Show example immediately after explaining it 2. Keep examples minimal but complete 3. Use realistic data (not "foo", "bar") 4. Show both request and response for API docs --- ## Cross-Linking Strategy - **Link first mention** of a concept in each section - **Don't over-link** – once per section is enough - **Link destinations:** Concept → conceptual docs, API action → endpoint, "Learn more" → deeper dive --- ## Page Length Guidelines | Page Type | Target | Reasoning | |-----------|--------|-----------| | Overview | 1-2 screens | Quick orientation | | Concept | 2-4 screens | Thorough explanation | | How-to | 1-3 screens | Task completion | | API endpoint | 2-3 screens | Complete reference | | Best practices | 3-5 screens | Multiple recommendations | If >5 screens, consider splitting. --- ## Quality Checklist - [ ] Content organized by user task, not system structure - [ ] Overview pages link to all child content - [ ] Section dividers separate major topics - [ ] Headings create scannable structure - [ ] Tables used for comparable items - [ ] Code examples follow explanations - [ ] Cross-links connect related content - [ ] Page length appropriate for type - [ ] Navigation connects sequential content --- ## Standards Loading (MANDATORY) Before planning documentation structure: 1. **Understand content types** - What documents will exist (conceptual, how-to, API reference) 2. **Load writing skills** - `ring:writing-functional-docs` and `ring:writing-api-docs` 3. **Review existing structure** - Understand current documentation hierarchy **HARD GATE:** CANNOT reorganize documentation without understanding content and audience. --- ## Blocker Criteria - STOP and Report | Condition | Decision | Action | |-----------|----------|--------| | Content inventory incomplete | STOP | Report: "Need complete list of documentation topics" | | User tasks undefined | STOP | Report: "Need user task list to organize around" | | Information architecture undefined | STOP | Report: "Need IA decisions before structuring" | | Navigation requirements unclear | STOP | Report: "Need navigation pattern decisions" | ### Cannot Be Overridden These requirements are NON-NEGOTIABLE: - MUST organize by user tasks (not system structure) - MUST include overview pages that link to children - MUST use section dividers (`---`) between major topics - MUST keep page length appropriate for document type - CANNOT nest deeper than H3 without good reason - CANNOT create orphan pages (must be linked) --- ## Severity Calibration | Severity | Criteria | Examples | |----------|----------|----------| | **CRITICAL** | Completely disorganized, no navigation | No hierarchy, orphan pages everywhere | | **HIGH** | Organized by system, not user tasks | "Database tables" instead of "Managing accounts" | | **MEDIUM** | Missing links, poor scannability | No cross-links, walls of text | | **LOW** | Structure works but could be optimized | Could improve navigation, add dividers | --- ## Pressure Resistance | User Says | Your Response | |-----------|---------------| | "Organize by our system components" | "MUST organize by user tasks. System structure ≠ mental model. I'll structure around what users do." | | "One long page is fine" | "Long pages overwhelm users. MUST split by document type guidelines. I'll organize appropriately." | | "Skip the overview pages" | "Overview pages are REQUIRED for navigation. I'll create overview pages linking to children." | | "Cross-links are extra work" | "Cross-links enable discovery. MUST connect related content. I'll add appropriate links." | | "Flat structure is simpler" | "Flat structure makes finding content harder. MUST use appropriate hierarchy." | --- ## Anti-Rationalization Table | Rationalization | Why It's WRONG | Required Action | |-----------------|----------------|-----------------| | "Mirrors our codebase structure" | Users don't know your codebase | **MUST organize by user tasks** | | "Everything on one page is convenient" | Convenience for whom? Not users | **Split per page length guidelines** | | "Deep nesting shows thoroughness" | Deep nesting hides content | **Keep hierarchy shallow (H3 max)** | | "Users will search anyway" | Search supplements, not replaces structure | **MUST provide clear navigation** | | "Links can be added later" | Orphan pages are lost pages | **Add links during creation** | | "Structure is aesthetic, not functional" | Structure IS functionality | **Structure enables findability** | --- ## When This Skill is Not Needed Signs that documentation structure is already correct: - Content organized around user tasks and goals - Clear hierarchy with appropriate depth - Overview pages link to all child content - Section dividers separate major topics - Navigation connects sequential content - Cross-links connect related topics - Page lengths appropriate for document type - No orphan pages **If all above are true:** Structure is correct, no reorganization needed. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/lerianstudio) — claim your Tome and manage your conversions.