[Policy Hub] Revamping the Documentation

[O-sura]

Problem:

The policy documentation within this repository lacks a standardized structure, which negatively impacts readability, discoverability, and long-term maintainability.

• Existing documents vary significantly in both section naming and organization.

Some policy documents adhere to a minimal structure (e.g., Overview, Features, Configuration, Examples, Use Cases), while others introduce additional or alternative sections such as How It Works, Configuring System Parameters in config.toml, Similarity Threshold Guidelines, Policy Behavior, etc. These sections are often semantically overlapping but inconsistently named or positioned.

• Configuration-related content is particularly fragmented, appearing under disparate headings such as Parameters, User Parameters (API Definition), System Parameters (config.toml), and Policy Parameters, with no clear or consistent distinction between user-facing and system-level configuration.

• Example content is presented under varying section titles, including API Definition Examples, Examples, and MCP Proxy Definition Examples.

Proposed Solution:

Adopt a standardized documentation structure for policy docs. Establishing and aligning on such a standard would improve documentation consistency, ease of navigation, and contributor onboarding. This should explicitly specify:

• Required versus optional sections
• Canonical section names
• Recommended ordering of sections

Document Structure

Every policy doc follows this 9-section structure. Required sections must always be present; optional sections are included only when they add value.

#	Section	Required	Purpose
1	Overview	Yes	What the policy does and when to use it
2	Features	Yes	Bullet list of capabilities
3	Configuration	Yes	All parameters, nested structures, and concept-specific subsections
4	Reference Scenarios	Yes	List of typical scenarios and working configs, error response examples, before/after transformations
5	Internal Architecture	No	In-depth explanation of the internal behavior (only for non-trivial policies)
6	Limitations	No	Constraints, non-goals, what the policy doesn't do
7	Notes	No	Caveats, best practices, security tips, performance guidance, troubleshooting
8	Related Policies	No	Links to related policies

Why have optional sections:

• Simple policies (e.g., add-headers, remove-headers) don’t require architectural or operational sections; optional sections keep documentation concise and focused while complex policies (e.g., semantic-cache, model-round-robin) might benefit from architectural, performance, and operational detail without imposing that overhead universally.

• A fixed set of core sections guarantees baseline completeness, while optional sections allow depth only where it meaningfully adds value.

---

Template

Overview:
      <!-- Explains what the policy does, what problem it solves. -->
Features:
    - <!-- Feature 1 -->
    - <!-- Feature 2 -->
    - <!-- ... -->
Configuration:
    - User Parameters (API Definition)
       <!-- Use when params are set per-API/route -->
    - System Parameters (Comes from config.toml)
       <!-- Use when the policy has gateway-level configuration -->
Reference Scenarios:
    <!-- Sample Use Case 1 -->
    <!-- Sample Use Case 2 -->
Internal Architecture:
     <!-- Optional. Include this section only if the internal operation requires explanation. -->
Limitations:
    <!-- OPTIONAL. -->
    - <!-- Limitation 1 -->
    - <!-- Limitation 2 -->
Notes:
    <!-- OPTIONAL. Consolidate best practices, security tips, performance guidance, troubleshooting here. -->
    - <!-- Note 1 -->
    - <!-- Note 2 -->
Related Policies
    <!-- OPTIONAL. -->
    - [Related Policy Name](../related-policy/v0.1/docs/related.md)

---

Migration Path for Existing Docs

Old Section	Migration Action
## How It Works	Rename to ## Internal Architecture
## Use Cases	Merge into ## Examples
## Error Handling / ## Error Response	Move content into ## Examples
## Request/Response Flow Examples	Merge into ## Examples
## Policy Behavior	Merge into ## Notes or ## Internal Architecture
## Best Practices	Merge into ## Notes
## Security Considerations	Merge into ## Notes
## Performance Considerations	Merge into ## Notes
## Troubleshooting	Merge into ## Notes
## System Configuration Example	Move into ## Configuration
Standalone concept sections (e.g., ## JSONPath Support)	Move under ## Configuration

[pubudu538]

+1 for the suggested changes. Instead of using Internal Architecture, better to use How it works or Policy Execution Flow/Model or similar thing.

[O-sura]

Let's go with How it works

[renuka-fernando]

We should also include the YAML section that needs to be included in the build.yaml section.

eg:

  - name: add-headers
    gomodule: github.com/wso2/gateway-controllers/policies/add-headers@v0

Ref: build.yaml disucssion: #875

[O-sura]

This will also get added under the configuration section.