Documentation
Created 2 years ago by ryanthompsonThe purpose of this discussion is to define the preferred structure, basic content, and guidelines for documenting PyroCMS and it's addons.
- [ ] Navigation Outline
- [ ] Structural Guidelines
- [ ] Markup Tools / Features
Navigation Outline
https://pyrocms.com/examples/documentation-navigation
Navigation structure should be normalized across all addons and documentation so that depth is controlled and users can acquire a sense of familiarity with organization.
Structure
- Primary Category
- Primary Topic
- Secondary Topic
- Primary Topic
Examples
Getting Started > Installation
Modules > Files Module (Core) > Uploading
Modules > API Module (PRO) > Issuing Tokens
Field Types > Relationship Field Type (Core) > Querying Relations
Structural Guidelines
- H1 reserved for titles
- h2 reserved for major sections
- h3 reserved for section topics
Addon Structure
All addons should include applicable overview, configuration, API, templating, and extensions sections.
Examples:
- h1: Installation
- h2: CLI Installation
- h3: Automating CLI installation
Markup Tools / Features
Contextual Notices
Contextual notices bring attention to small details regarding the documentation.
- Video: See related video / series link (purple/brand)
- Guide: See related guide link (green)
- Tip: Callout small feature (blue)
- Warning: Warn about a feature (perhaps "note") (orange)
- Important: High priority callout about a feature (red)
Features
- Automated page jump for h1, h2, h3, h4
- Automated code examples
Work in progress
This is well under way already. Unpinning.