Documentation

Documentation

Created 8 months ago by ryanthompson

The 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

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