---
title: "Updated Metrics and Measurement section in API course to remove scoring aspect"
date: 2022-02-08
description: "Why remove the scoring aspect of criteria? Consolidating the checklists A lightweight checklist Best outcome of the quality checklists ..."
canonical_url: https://idratherbewriting.com/blog/updated-api-measurement-section
---

> For AI agents: a documentation index is available at https://idratherbewriting.com/llms.txt. Markdown versions of all pages are available by appending .md to any page URL.

# Updated Metrics and Measurement section in API course to remove scoring aspect

> I recently updated the [Metrics and measurement](https://idratherbewriting.com/learnapidoc/docapis_metrics_and_measurement.html) section of my API course to remove the section on scoring the various API documentation criteria. I also consolidated the first- and second-level checklists into a [single checklist](https://idratherbewriting.com/learnapidoc/docapis_quality_checklist.html).

## Why remove the scoring aspect of criteria?

I initially thought that I could give each criteria a score, weight each score, and then give an overall grade or score for developer docs. But as I did that recently at work, revisiting each criteria and its score that I’d assigned one year earlier with a new annual assessment and score, the scores felt silly. I don’t think they worked well and seemed meaningless. So in the spirit of getting rid of things that don’t work, I removed that scoring section from my API doc course. It seems that achieving that elusive metric about how to quantify tech comm work is still something I haven’t figured out.

## Consolidating the checklists

Also, I originally had a first-level checklist and a second-level checklist. The idea was that you could only assess some aspects of a developer portal after becoming more familiar with the content. However, I consolidated both checklists into a [single checklist](https://idratherbewriting.com/learnapidoc/docapis_quality_checklist.html) for the sake of convenience. I think that most people can naturally exclude criteria they don’t have enough information about. I’d rather have all the criteria in one place.

## A lightweight checklist

Finally, I created a [lightweight checklist](https://idratherbewriting.com/learnapidoc/docapis_quality_checklist.html#short_version) that selects only two criteria from each category. I tried to select what I felt would be the most important criteria, but really it came down to a purely arbitrary decision on my part.

## Best outcome of the quality checklists

I made these updates after a recent podcast where we discussed the checklists. The podcast isn’t yet published, but stay tuned for more on the topic of API documentation quality checklists. I’ve found that the best outcome of the checklists is my “Observation 3” that I published in [10 observations after using my API documentation checklist in a real scenario](https://idratherbewriting.com/blog/observations-using-checklist/), about a year ago:

> **Observation 3: The checklist does a wonderful job at opening up a critical look at API docs**
>
> Although one of my motivations was to create metrics around quality, as I did an initial assessment of the docs I’m working on, I found that the checklist does a wonderful job in opening up a critical view and analysis of the documentation. It opens up a more critical perspective that lets you slice up different dimensions and aspects of the docs. Regardless of whether the scoring and quantitative metrics goes anywhere, the set of characteristics provides an incisive way to investigate doc quality.
>
> If you’re looking to audit a site and get a sense of what should be improved, try going through the [checklist of questions](https://idratherbewriting.com/learnapidoc/docapis_quality_checklist.html). You’ll have a lot to think about this way, and it provides a more structured approach than random observations.