Skip to main content

Multi-language examples where applicable

ab-001006 · developer-documentation.content-quality.multi-language
Severity: lowactive

Why it matters

REST APIs and multi-language SDKs with examples in only one language silently exclude entire developer audiences. A Python backend engineer evaluating your API should not have to mentally port JavaScript examples; a mobile developer working in Swift should not need to read curl to figure out a request shape. The cost is measurable in rejected integrations, drive-by support tickets ("how do I do this in Go?"), and underperforming SDKs whose docs languish behind the flagship language.

Severity rationale

Low because missing language coverage is a discoverability friction, not a broken integration.

Remediation

Add at least two language examples to every API reference page — typically curl plus the primary SDK language. Use a tabbed code block component or sequential fenced blocks in docs/api/*.md. Example:

curl -X POST https://api.example.com/users \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"Jane"}'
user = client.users.create(name="Jane")

For SDK docs, each published SDK gets its own example section.

Detection

  • ID: developer-documentation.content-quality.multi-language

  • Severity: low

  • What to look for: If the project is an API or service that can be consumed from multiple programming languages, check whether documentation provides examples in more than one language. This is most relevant for REST APIs (curl + at least one language), multi-platform SDKs, and services with official client libraries in multiple languages. Count all instances found and enumerate each.

  • Pass criteria: API documentation includes examples in at least 2 languages (e.g., curl + JavaScript, or Python + TypeScript). If official SDKs exist in multiple languages, each has examples in its respective language.

  • Fail criteria: API can be consumed from any language but examples only show one language, or official SDKs exist in 3+ languages but only one has documentation.

  • Skip (N/A) when: The project is a single-language library (not an API/service), or is explicitly for one language only (e.g., a React component library).

  • Detail on fail: Example: "REST API documentation only shows curl examples -- no JavaScript, Python, or other language examples" or "Official SDKs exist for Python, JavaScript, and Go but only Python SDK is documented"

  • Remediation: Add examples in at least the two most common consumer languages. Use tabs or language selectors:

    ### Create a User
    
    **curl:**
    ```bash
    curl -X POST https://api.example.com/users \
      -H "Authorization: Bearer YOUR_KEY" \
      -d '{"name": "Jane"}'
    

    JavaScript:

    const user = await client.users.create({ name: 'Jane' })
    

    Python:

    user = client.users.create(name="Jane")
    

Taxons

History