Quality checklist for API docs (simplified html) -- short version

FINDABILITY

Findable in search

The content is indexed in a general search engine and findable when you create searches with the product name and some key tasks.

Assessment:

Release notes present

Release notes track changes to the product and documentation.

Assessment:

ACCURACY

Steps are accurate

The steps in the tasks accurately lead to the results promised by the task, without missing any details. For example, if the instructions say to click a button name, the button is named the same way in the interface. If the instructions say to use a class, the class is spelled as it appears in the code library, etc.

Assessment:

Code samples work

Code samples that can be copy and pasted actually work.

Assessment:

RELEVANCE

Key use cases are documented

The documentation doesn't just provide reference information (e.g., auto-generated API documentation) but also explains how to use the API with tutorials guiding users through common use cases and journeys. The content should address the *most common* use cases intended for the product.

Assessment:

Code samples exist

Code samples showing sample ways to use the API (or similar tools) are provided. Ideally, the code samples are available in the user's target language. This might mean providing multiple code samples.

Assessment:

CLARITY

Product overview page answers "wh" questions

The overview explains the big picture and describes the problem that the tool or service addresses. Common who/what/where/why questions are answered here.

Assessment:

Access and authorization explained

Details about how to get access, permissions, and authorization to use the API are provided. For example, this topic might cover how to authorize an API call with API keys.

Assessment:

COMPLETENESS

Reference docs follow industry standards

For native library APIs (or other API types), reference docs (auto-generated from source code comments) are available. This might mean Javadoc, Doxygen, OpenAPI outputs like Swagger or other reference docs specific to the library. The reference docs should be populated and generally follow tagging standards.

Assessment:

Parameter docs have complete info

Parameter documentation typically includes a description, data type, min/max values, sample values, and optional/required usage.

Assessment:

READABILITY

Grammar isn't distracting

Sentences are grammatically correct and read well, without distracting the user or calling attention to the language.

Assessment:

Placeholder text in code is visually apparent

In code samples, placeholder text that needs to be customized is clearly indicated to the user. It's not confusing what is code and what needs to be changed, like `APIKEY`.

Assessment: