Explanation

Use explanation pages when you want context on platform design choices and trade-offs.

Rationale

These decisions prioritize clarity for readers and maintainable delivery workflows for the team.

Why root and docs are split

• devdocify.com serves marketing intent and product positioning.
• devdocify.com/docs serves technical guidance and implementation detail.
• Keeping these surfaces distinct avoids mixing conversion copy with technical reference content.

Why this site includes TfL and Petstore

• They demonstrate multi-docset navigation and authoring patterns.
• They provide realistic API playground examples without requiring private backend systems.
• They let the first-party docs explain platform behavior using live, inspectable examples.

Why docs-as-code is central

• Reviewers check each docs change in a pull request.
• Build, content, assistant, Lighthouse, and playground health checks run before merge.
• Preview workflows make UI/content regressions visible before production.

Why search is generated during builds

• The search index includes documentation pages and API operations.
• The generated index gives Algolia stable facets for docset, version, and type.
• CI can skip the push safely when production Algolia credentials are unavailable.

Why SAML access is separate from the static build

• SAML enforcement happens at the proxy or platform layer, not inside generated HTML.
• You can serve the same build output openly or behind SSO, without a rebuild.

Why diagrams are text-first

• Reviewers check Mermaid and PlantUML source in pull requests, like any other text.
• PlantUML blocks render without adding a Java dependency to CI.
• Architecture diagrams stay close to the docs that explain the system behavior.

Platform component overview