docs: tighten ATTRIBUTES heading and intro

reuvenharrison · claude · reuvenharrison · commit 2c1cdd33bc8d · 2026-04-30T19:28:04.000+03:00
- Heading was 12 words ("Adding custom attributes to changelog
  entries basing on OpenAPI extension tags") and used "tags", which
  is a different OpenAPI concept. Shortened to "Add OpenAPI
  Extensions to the Changelog" — matches the README link text.
- Intro said "Some people annotate their endpoints with OpenAPI
  Extension tags" — vague subject and wrong terminology. Replaced
  with a definition-first sentence that describes what the x-*
  fields are.
- Tightened the trailing prose ("Oasdiff can add these attributes
  ... as follows" → "Use the --attributes flag to include these
  values in JSON or YAML changelog entries").

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/ATTRIBUTES.md b/docs/ATTRIBUTES.md
@@ -1,5 +1,5 @@
-# Adding custom attributes to changelog entries basing on OpenAPI extension tags
-Some people annotate their endpoints with OpenAPI Extension tags, for example:
+# Add OpenAPI Extensions to the Changelog
+OpenAPI specs can carry custom `x-*` extension fields that attach metadata to operations. For example:
 ```
 /restapi/oauth/token:
   post:
@@ -12,7 +12,7 @@ Some people annotate their endpoints with OpenAPI Extension tags, for example:
         ...
 ```
 
-Oasdiff can add these attributes to the changelog in JSON or YAML formats as follows:
+Use the `--attributes` flag to include these values in JSON or YAML changelog entries:
 
 ```
 ❯ oasdiff changelog base.yaml revision.yaml -f yaml --attributes x-audience
