Technical Documentation & SOPs

Use numbered steps to produce structured deliverables for each task. Each step specifies input, action, output format, success criterion, and rationale.

Transforming Dense Swagger YAML into Scannable Endpoint Guides

1. Parse the input Swagger YAML file.

   • Input: Raw Swagger YAML string or file path.
   • Action: Load using js-yaml parser; validate against OpenAPI schema with Ajv.
   • Output: Validated JSON object with endpoints list.
   • Success criterion: No validation errors; all $ref resolved.
   • Rationale: Ensures data integrity before transformation, preventing downstream errors from malformed specs.

2. Calculate schema complexity score for each endpoint schema.

   • Input: Parsed JSON schemas from Step 1.
   • Action: Run Node.js script: (properties count × 1.5) + (nesting depth × 5) + (10 per allOf/oneOf) + (2 per array of objects).
   • Output: Per-endpoint score (e.g., {endpoint: '/v1/charge', score: 62}).
   • Success criterion: Scores computed for 100% of endpoints.
   • Rationale: Quantifies density to guide simplification, avoiding uniform treatment of simple vs. complex schemas.

3. Conduct audience analysis.

   • Input: Endpoint list from Step 1; available personas or usage data.
   • Action: Classify primary users (developers vs. QA) based on context; prioritize auth flows for developers.
   • Output: Prioritized endpoint order (e.g., auth first, then CRUD).
   • Success criterion: Order covers 70% dev traffic if logs available.
   • Rationale: Matches structure to user needs, reducing time-to-first-call.

4. Prioritize endpoints using composite metric.

   • Input: Endpoint list; Datadog/CloudWatch logs (>1,000 calls/week) + Zendesk tickets (>25/quarter).
   • Action: Rank by traffic volume descending; apply 70/20/10 coverage split (top endpoints first).
   • Output: Sorted endpoint queue (e.g., /v1/payments first).
   • Success criterion: Top 3 endpoints cover ≥70% calls.
   • Rationale: Focuses effort on high-impact endpoints, validated by quarterly GA A/B tests.

5. Chunk endpoints into pages.

   • Input: Prioritized list; Spectral/Redocly CLI for schema overlap (≥70%); Datadog traces (≥40% co-occurrence); Zendesk refs (≥20% interchangeable).
   • Action: Group if all criteria met (same resource + overlap + co-occurrence + refs); else solo page. Apply Confusion Override if Zendesk clustering >25% error-linked and OpenAPI Diff score <10%.
   • Output: Page groups (e.g., ['/v1/payment_intents/LIST+CREATE'] or ['/v1/charge'] solo).
   • Success criterion: Groups justified by all metrics; overrides logged.
   • Rationale: Balances comprehensiveness with scannability; solo pages for low-traffic (<500 calls/week) prevent bloat.

6. Bullet-point parameters with flags.

   • Input: Schema from Step 1, simplified per Step 2.
   • Action: List as 'name: Required: Yes/No, Type: string/integer, ...'.
   • Output: Markdown bullets per endpoint.
   • Success criterion: ≤15 items; core fields only if score >50.
   • Rationale: Enables quick scanning, cutting comprehension time.

7. Generate live curl examples.

   • Input: Endpoint details; Postman-like validation.
   • Action: Produce curl commands for key scenarios (e.g., curl -X POST https://api.example.com/v1/charge -H "Authorization: Bearer ..." -d '{"amount":1000}'); validate against schema.
   • Output: Tested curl strings + expected JSON.
   • Success criterion: Commands parse without syntax errors; match schema.
   • Rationale: Provides copy-paste success, reducing trial-error loops.

8. Perform visual validation.

   • Input: Assembled Markdown/YAML.
   • Action: Export to OpenAPI YAML; lint with Spectral for cycles; confirm Stoplight-compatible structure.
   • Output: Validated YAML + lint report.
   • Success criterion: Zero lint errors; renders in mock tools.
   • Rationale: Catches formatting issues pre-publish.

9. Assemble final deliverable.

   • Input: All prior outputs.

   • Action: Structure into rigid six-section Markdown template; prepare PR description template listing changes.

   • Output:

     # Endpoint Guide: [Path/Method]
     
     ## Overview
     Hero summary ≤200 words. Quickstart curl. Auth method. Path. Idempotency notes.
     
     ## Parameters
     | Name | Type | Required | Description (≤1 sentence) | Validation | Default | Example |
     |------|------|----------|---------------------------|------------|---------|---------|
     | amount | integer | Yes | Charge amount in cents. | >0 | | 1000 |
     *(≤15 rows; collapsible full schema toggle)*
     
     ## Response
     Mirrors Parameters table for 200 OK/4xx/5xx.
     
     ## Examples
     ```bash
     curl -X POST ...
     

     SDK/JSON pairs.

     Errors

     Common codes from tickets + mitigations/trace IDs.

     Related Resources

     Upstream/downstream links + changelog.

   • Success criterion: Matches template; GitHub Actions CI would pass.

   • Rationale: Enforces scannability; yields 12-22% scroll-depth/support lifts.

Auditing Legacy Docs for Compliance Gaps

1. Scan for regulated terms.

   • Input: Doc text/HTML.
   • Action: Regex search in Oxygen XML Editor emulation (e.g., /email|SSN|GDPR/).
   • Output: List of matches with context.

2. Cross-reference against standards.

   • Input: Matches; compliance matrix.
   • Action: Use Excel-like table: rows=issues, columns=standard (e.g., 'Data Retention: Specifies 30 days? Y/N').
   • Output: Tagged issues (HIGH-RISK: Anonymize example emails).
   • Success criterion: 100% issues scored.

Modularizing Content for Single-Sourcing

1. Identify repeats.

   • Input: Full doc set.
   • Action: Flag content repeating >3 times (e.g., error codes table).
   • Output: Snippet list.

2. Chunk into reusables.

   • Action: Extract to standalone topics where each answers one question.
   • Output: MadCap Flare-like snippets (e.g., reusable table Markdown).
   • Rationale: Prevents drift; enables platform-agnostic reuse.