What should I use for docs that support multiple environments?

For docs that need to support multiple environments, use environment-specific docs with shared reusable content.

A good pattern is:

• One source of truth for shared concepts, workflows, and API behavior
• Environment overlays for things that differ by env, like:
  • URLs/endpoints
  • auth credentials/setup
  • feature flags
  • resource names
  • limits or availability
• Clear labels in the docs so readers know which parts are:
  • universal
  • dev/test/staging-specific
  • production-specific

Common ways to implement this:

1. Conditional content
   Use variables or conditional blocks in your docs system to render env-specific values.

2. Separate config files Keep environment settings in YAML/JSON/INI files and inject them into the docs build.

3. Tabs or environment switchers Let readers select “Dev / Staging / Prod” to see the relevant values.

4. Separate pages only when necessary If the environments differ a lot, split them into env-specific pages, but avoid duplicating everything.

If you’re asking about a documentation format/tool choice, good options are:

• Markdown + variables/templates for flexibility
• AsciiDoc if you want stronger reuse/include support
• Docusaurus / MkDocs / Sphinx if you want a docs site with environment-specific builds

If you want, I can recommend the best approach based on your stack, like static docs, OpenAPI docs, or internal runbooks.