1. Forum
  2. Roadmap
  3. Documentation

Documentation

ryanthompson - 2 months ago

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

ryanthompson - 1 month ago

This is well under way already. Unpinning.