shared-docs-demo

This repository contains centrally maintained user documentation that can be reused across multiple repositories via Git submodules.

What This Repository Shows

• Shared Markdown documentation stored in one central location
• A submodule-friendly structure under docs/
• A controlled update model where consumer repositories choose when to adopt a newer shared docs version

Repository Structure

• docs/index.md: central entry point for consumers
• docs/getting-started.md: onboarding overview
• docs/access.md: baseline access guidance
• docs/access-guide.md: expanded access guidance added in the next approved release
• docs/support.md: support model

Maintainer Workflow

1. Update the shared Markdown files in this repository.
2. Commit the change in shared-docs-demo.
3. Create a release tag for the approved documentation baseline.
4. Consumer repositories can then update their submodule reference when they are ready.

Consumer Workflow

Consumer repositories are expected to embed this repository as a submodule at docs/shared-docs.

Example setup:

git submodule add https://github.com/commutativity/shared-docs-demo.git docs/shared-docs
git commit -m "Add shared documentation submodule"

Clone with submodules:

git clone --recurse-submodules <consumer-repo-url>

If the repository was cloned without submodules:

git submodule update --init --recursive

To move a consumer repository to a newer approved shared docs release:

git submodule update --remote docs/shared-docs
git add .gitmodules docs/shared-docs
git commit -m "Update shared docs submodule"

Important: the submodule records a concrete commit. Consumers do not update automatically unless someone updates the submodule pointer and commits that change in the consumer repository.

When Submodules Make Sense

Git submodules fit well when:

• documentation is maintained centrally
• consumers mostly read the content instead of editing it locally
• each repository should choose when to adopt a newer shared baseline

They are less attractive when many consumer repositories need constant parallel edits to the same documentation. In that case, publishing docs from one source or automating sync with CI may be a better fit.