Documentation
Created 1 year 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

ryanthompson  —  1 year ago

This is well under way already. Unpinning.
https://pyrocms.com/forum/channels/roadmap/documentation
pyrocms.com
crawl=CC-MAIN-2020-16
33261
application/http; msgtype=response
sha1:TPSBCNGVO4WT64AC3EIPSNZEWP64EXZC
<urn:uuid:dbad24b6-07f1-4ed7-ad65-a2e97c3b058d>
2020-04-04T02:05:47Z
104.26.9.63
text/html
sha1:SVOZOVOO3YPGHNUDENMLCVI5R6WNJ34Q
<urn:uuid:5045ffbd-857b-4f44-998b-12eb4f27e1ae>
https://pyrocms.com/forum/channels/roadmap/documentation
response
<urn:uuid:8358dee1-2143-4ea8-9a5e-8a8532eb197d>
isPartOf: CC-MAIN-2020-16
publisher: Common Crawl
description: Wide crawl of the web for March/April 2020
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-67-67-222.ec2.internal
software: Apache Nutch 1.16 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 1.1-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: http://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/