Search results

Second-level checklist for API documentation

Last updated: Feb 15, 2021

This section continues from the previous page, First-level checklist for API documentation.

In the previous topic, I described a first-level checklist for API documentation that you can do without more familiarity with the docs. This section describes more characteristics to evaluate that will only be discernible when you have more familiarity with the docs.

Second-level documentation checklist

Second-level API documentation quality checklist

Findability

Accuracy

Relevance

Clarity

Completeness

Readability

Is this list complete? No

Between the two checklists (first-level and second-level), there are about 75 different characteristics that I’ve described. Did I miss anything? Sure, you could probably expand this list with 100 more characteristics.

Sometimes it’s not clear what needs to be added until you see docs that are missing some key element or which violate some assumed principle. Feel free to let me know (in the comments below) what could/should be added, especially if it’s a major omission.

However, there’s also something to be said for a practical list of key points. The more criteria you add, the more laborious it becomes to evaluate docs. The most popular style guides (e.g., Strunk and White) are those that briefly cover the main points you need rather than providing an exhaustive list, especially if many guidelines are already followed.

Continue on to the next section, Quantifying your progress.

Buy me a coffeeBuy me a coffee
Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,500+ subscribers. (See email archive here.)

147% Complete

147/162 pages complete. Only 15 more pages to go.