Improve documentation about writing release notes (#2038)

* chore: improve release notes documentation

* chore: adjust tests

websites/docs-smoke-test/src/releases/release-format-definition.mdx

@@ -34,7 +34,7 @@ The file can live in folders to better organize large numbers of past release no
 
 The file can use any MDX allowed in documentation, but it's strongly advised to only use basic markdown and no headings before the "read more" separator.
 
-Metadata is defined in YAML frontmatter.
+Metadata are defined as YAML frontmatter.
 
 The URL of this release notes details page inside a microsite would be `/releases/2000-03-03-release-note-format-definition`.
 
@@ -44,14 +44,17 @@ The URL of this release for example in the merchant-center microsite would be `h
 
 The `<!--more-->` syntax for separating out the long form from the part shown in the list is to be taken over from the Jekyll convention. Unprepared new users have understood it intuitively because it's explicit and the company knows it already.
 
-## Frontmatter:
+## Frontmatters:
 
-- `date` (date, required): A `YYYY-MM-DD` date format (not a text, it's parsed as an ISO date)
-- `orderHint` (number, optional): A number that indicates the order of release notes with the same release date in the RSS feed.
-- `title` (string, required): The title for the website
+- `date` (date, required): A `YYYY-MM-DD` date format (not a text, it's parsed as an ISO date).
+- `title` (string, required): The title for the website.
 - `description` (string, required): Max 256 characters plain text containing the change and its advantage ("tweet-able" and for RSS).
   256 = 280 twitter minus 23 for a link. Do not imply the title, this text is used stand-alone in Merchant Center and other feed recipients. It must convey the value proposition and key change topic.
-- `type` (string, optional): Must be either `feature` (for "New Feature"), `fix` (for "Resolved Issue") or `enhancement` (for "Enhancement")
+- `type` (string | string[], required): Must be either `feature` (for "New feature"), `enhancement` (for "Enhancement"), `fix` (for "Resolved issue"), `announcement` (for "Announcement") or `deprecation` (for "Deprecation").
+- `orderHint` (number, optional): Sorts release notes that share the same release date. Uses an ascending order with 1 being the most recent release note and 20 being the oldest. This logic works across multiple microsites. If you have multiple release notes from different microsites with the same release date, add this frontmatter to the respective release notes to sort them accordingly from 1 to 20.
 - `topics` (array of string, optional): YAML array of free to choose text entries. The Filter UI may be constrained to pre-defined topics.
 - `published` (boolean, optional, defaults to `true`): `false` prevents rendering of the release in the site. **Should not be used in the main documentation**, reserved for atypical situations. Not included in the template.
-- `slug` (string, optional, defaults to `$date-$title` (slugified)): optional, allows overriding the autogenerated URL slug. **Should not be used in the main documentation**, reserved for migrating legacy docs.
+- `slug` (string, optional, defaults to `$date-$title` (slugified)): Allows overriding the autogenerated URL slug. **Should not be used in the main documentation**, reserved for migrating legacy docs.
+- `product` (string, optional): Used in the release notes search to filter by product. If set, it overrides the `product` defined in the website `gatsby-configure.mjs`. Please note that in case an array is defined, just the first value is used for filtering purposes.
+- `productArea` (string, optional): Used in the release notes search to filter by product area. If set, it overrides the `title` defined in the website `gatsby-configure.mjs`.
+- `hideProductLabels` (boolean, optional): Used to hide the product and productArea labels on the release note details and list page.

websites/documentation/src/content/writing/release-notes.mdx

@@ -12,7 +12,7 @@ See the [test site](/../docs-smoke-test/releases) for an example.
 
 # Creating a new release note
 
-Release note files can be found in `src/content/releases` and are written in MDX like regular content. You can also place files in folders to better organize the release notes.
+Release note files can be found in `src/releases` and are written in MDX like regular content. You can also place files in folders to better organize the release notes.
 
 <Info>
   The Docs-Kit provides an interactive command-line script to create new release notes.
@@ -21,7 +21,7 @@ Calling `yarn create-docs-release-note` in the terminal guides through the creat
 </Info>
 
 The files' location does not imply the URL like for content.
-The URL is built from the frontmatter fields for date and title.
+The URL is built from the frontmatter fields for date and title. (The URL can also be customized by the `slug` frontmatter. Read more about available frontmatters below.)
 This way you can reorganize the files without changing the URL of the release note.
 
 To learn the full release note file format including the full specification of the frontmatter fields, see the [specification by example file](/../docs-smoke-test/releases/2000-03-03-release-note-format-definition-custom).
@@ -37,7 +37,7 @@ title: (TEMPLATE) TITLE
 description:
   | # title content and what this is good for //  max 256 characters // for MC, RSS and other feeds
   (TEMPLATE) DESCRIPTION
-type: enhancement # feature | fix | enhancement | announcement
+type: enhancement # feature | fix | enhancement | announcement | deprecation
 topics:
 # uncomment matching topics. Stay focused.
 #  - Products
@@ -60,8 +60,8 @@ If there is no more, remove the marker above, too.
 
 ## Available frontmatters:
 
-- `date` (date, required): A `YYYY-MM-DD` date format (not a text, it's parsed as an ISO date)
-- `title` (string, required): The title for the website
+- `date` (date, required): A `YYYY-MM-DD` date format (not a text, it's parsed as an ISO date).
+- `title` (string, required): The title for the website.
 - `description` (string, required): Max 256 characters plain text containing the change and its advantage ("tweet-able" and for RSS).
   256 = 280 twitter minus 23 for a link. Do not imply the title, this text is used stand-alone in Merchant Center and other feed recipients. It must convey the value proposition and key change topic.
 - `type` (string | string[], required): Must be either `feature` (for "New feature"), `enhancement` (for "Enhancement"), `fix` (for "Resolved issue"), `announcement` (for "Announcement") or `deprecation` (for "Deprecation").
@@ -71,7 +71,7 @@ If there is no more, remove the marker above, too.
 - `slug` (string, optional, defaults to `$date-$title` (slugified)): Allows overriding the autogenerated URL slug. **Should not be used in the main documentation**, reserved for migrating legacy docs.
 - `product` (string, optional): Used in the release notes search to filter by product. If set, it overrides the `product` defined in the website `gatsby-configure.mjs`. Please note that in case an array is defined, just the first value is used for filtering purposes.
 - `productArea` (string, optional): Used in the release notes search to filter by product area. If set, it overrides the `title` defined in the website `gatsby-configure.mjs`.
-- `hideProductLabels` (boolean, optional): Used to hide the product and productArea labels on the release note page.
+- `hideProductLabels` (boolean, optional): Used to hide the product and productArea labels on the release note details and list page.
 
 ## Release note's search indexing