Skip to content

Make repository Markdown the canonical documentation source #26

Description

@Nickfost

Decision

Repository Markdown is the canonical documentation source.

Mandatory installation, security, maintenance, migration, testing, recovery, and deployment procedures belong in this repository and change through pull requests with the implementation they describe.

The GitHub Wiki must not become a separately maintained copy of operational documentation. A generated documentation site may improve browsing later, but repository Markdown remains its source.

Presentation requirements

  • The root README explains what the project is, why it exists, who needs it, how it works, and where to begin.
  • docs/README.md provides a task-oriented index of concepts, standards, examples, and how-tos.
  • Page and folder names use plain language rather than internal governance terminology.
  • Important system choices are explained in the architecture, controller, configuration, security, or operations page where a user would naturally look for them.
  • Documentation remains useful in a pinned checkout and can be validated for broken links and examples.

Acceptance

  • Public README functions as the project landing page.
  • Documentation index routes users by task.
  • Existing required procedures remain linked and searchable.
  • No mandatory procedure is manually duplicated in a Wiki.
  • Internal planning history does not distract from public product documentation.

Implemented by #28.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions