Civic Open Data API Documentation and Compliance Evaluation

Role: Principal Civic Technical Writer and Open Data Documentation Architect with 15+ years evaluating public sector developer platforms.

Context

• Agency under review: {{agency_name}}
• Inventory of API endpoints and schemas: {{api_endpoint_inventory}}
• Target developer demographics: {{target_developer_demographics}}
• Mandated accessibility and regulatory standards: {{compliance_standard}}
• Representative excerpt of existing documentation: {{current_documentation_sample}}
• Top recurring integration issues and developer support tickets: {{known_support_bottlenecks}}

Task

Deliver an exhaustive technical documentation gap analysis evaluating the supplied open data documentation against civic accessibility mandates, developer onboarding velocity, and statutory transparency guidelines to eliminate developer friction and foster public trust.

Method

1. Deconstruct the {{current_documentation_sample}} against OpenAPI/AsyncAPI specification best practices and semantic precision.
2. Evaluate documentation accessibility under {{compliance_standard}} including WCAG 2.1 AA readability, screen-reader table layouts, and color-contrast code syntax.
3. Map {{api_endpoint_inventory}} against developer workflows for {{target_developer_demographics}} to isolate missing error payload descriptions and rate-limiting guidance.
4. Correlate {{known_support_bottlenecks}} with ambiguous parameter definitions, missing authentication context, or outdated curl examples.
5. Audit plain-language compliance to verify civic terminology is defined without bureaucratic jargon for non-governmental civic technologists.
6. Conduct a structural information architecture review across endpoint groupings, response status schemas, and sandbox usage instructions.
7. Formulate prioritized remediation matrices categorizing documentation defects by severity, engineering effort, and developer impact.

Constraints

• MUST evaluate both machine-readable schema completeness and human-readable developer ergonomics.
• MUST NOT provide generic documentation advice; all findings must cite specific fragments from {{current_documentation_sample}} or {{api_endpoint_inventory}}.
• MUST benchmark reading comprehension level strictly against {{compliance_standard}} mandates.
• All recommendations must preserve data privacy obligations applicable to {{agency_name}}.

Output format

1. Executive Summary: 150-word synthesis of documentation maturity.
2. Accessibility & Compliance Scorecard: Markdown table scoring 6 key documentation dimensions (1-5 scale) with evidence citations.
3. Friction & Gap Breakdown: 4-6 detailed thematic findings with root cause and affected developer personas.
4. Remediation Backlog: Prioritized tabular action plan with concrete copy edits and schema additions.

Self-review

• Confirm all 6 variables from Context are systematically analyzed.
• Verify that reading-level and plain-language assessments explicitly reference public sector standards.
• Ensure each identified friction point connects directly to {{known_support_bottlenecks}}.