Skip to content

Contribute

This page describes the requirements for PCA to publish documentation on the PCA Documentation Hub.

Purpose

To ensure quality, trust, and maintainable synchronization, all published documentation should follow a small set of common technical requirements.

Meeting these requirements helps PCA onboard and synchronize documentation efficiently while keeping the hub consistent for users.

Publishing Requirements

To be accepted for publication on this hub, documentation should meet all of the following.

Official PCA GitHub repository

  • The source should live in an official PCA GitHub repository.
  • This ensures the source is trusted and endorsed by PCA.
  • PCA can provide a starter repository based on an approved template that already satisfies the core Documentation Hub requirements.
  • If you need a new documentation repository, send a request to support@posccaesar.org.

MkDocs and Markdown

  • Documentation should be authored in Markdown and built with MkDocs.
  • Repositories that do not use MkDocs are currently not supported in this hub.

Dedicated documentation scope when a repository contains more than documentation

  • If a repository includes code, tools, or other non-documentation material, the MkDocs documentation should be organized in a dedicated folder structure.
  • The documentation section should be clearly isolated so it can be synchronized reliably into the Documentation Hub.

Non-technical users should be able to contribute

  • Non-technical users can contribute through Pages CMS.
  • Pages CMS must be granted access to the specific repository.
  • Access can be requested by emailing support@posccesar.org.

At a high level, PCA recommends:

  • a clearly defined MkDocs project boundary
  • a dedicated documentation directory with Markdown sources
  • stable, predictable paths for docs and assets used by those docs

Additional Technical Requirements

Based on the current source-repo pattern used for PCA documentation, contributors should also keep the following high-level technical requirements in mind:

  • the repository should keep all published documentation inside a docs/ folder
  • the repository should include a root docs/index.md page
  • if you want a folder to appear as a section in navigation, that folder should include its own index.md
  • folders act as sections and Markdown files act as pages
  • the MkDocs project boundary should remain simple and predictable, typically with mkdocs.yml at the repository root and docs_dir: docs
  • media and content paths should remain stable within the boundaries of the docs/ folder

Important Stability Rules

To keep synchronization with the PCA Documentation Hub reliable:

  • do not rename or remove the docs/ folder
  • do not delete docs/index.md
  • do not make unnecessary structural changes to mkdocs.yml or .pages.yml

These requirements are intentionally simple. The goal is to make documentation easy to maintain, easy to synchronize, and safe for both technical and non-technical contributors.