Changelog feedback

[sarahsanders-docker]

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

Other

Description

Task: Read a changelog (e.g., Hug API changelog). What could help you better understand what changed and why?

Location

https://docs.docker.com/reference/api/hub/latest-changelog/

Suggestion

No response

[pbj-writes]

Taking a look! 👀

[pbj-writes]

Summary Sentence

Here you can learn about the latest changes, new features, bug fixes, and known issues for Docker Service APIs.

Parsing this, the changelog can document:

• Changes
• New Features
• Bug Fixes
• Known Issues

I'm feeling some terminology ambiguity and overlap. Maybe a quick rewrite to distinguish 'changes' from the change 'subtypes':

Here you can learn about the latest changes including new features, bug fixes, and known issues for Docker Service APIs.

But maybe this isn't quite right either because a known issue isn't a change. Trying another rewrite to inspire some inertia:

Here you can learn about new features, bug fixes, and known issues for Docker Service APIs.

⬆️ Shorter and sweeter. This eliminates the cognitive effort to parse the word "changes" and distinguish that from change subtypes and known issues.

Entries

Looks like the intention is to have a cumulative list of changes. Forever? Last two years?

Does or should versioning play a role? For instance, looks like the two available changes are against the latest Docker Service APIs. Are there other uses cases where you could update something that's not the latest? If so, some explicit tags like v1, v2 might help with short term context disambiguation and long term organization/filtering of changes.

Extrapolating a bit, the layout looks like:

• DATE (new changeling entry)
  • CHANGE GROUP TYPE (e.g., NEW)
    • New thing 1
    • New thing 2
  • CHANGE GROUP TYPE (e.g., BUG FIX)
    • Squashed bug 1
    • Squashed bug 2

As the list grows, I wonder how useful the ToC will be since it'll just be many YYYY-MM-DDs.

The bullets are in present tense. I think there's a better tense for those. When I read "Add...", it's possible to interpret that as some action/task that must be done.

I think if there's consistency between how the summary sentence is written and your entry change group types, then I think this becomes an easy info architecture for users to grasp.

@sarahsanders-docker