Victor Wu
--- a/source/handbook/marketing/blog/release-posts/index.html.md

+ 37

− 7
+++ b/source/handbook/marketing/blog/release-posts/index.html.md

+ 37

− 7
 @@ -273,24 +273,54 @@ Feature blocks in the YAML data file contain the following entries, as exemplifi
    Lorem ipsum dolor sit amet, [consectetur adipisicing](#link) elit.
 ```

-These entries represent:
+#### Feature Name

 - `name`: feature name, capitalized
+
+Use a short and strong name for all feature names.
+
+#### Feature Availability
+
+Use the following pattern to apply the correct badge to the feature (CE, EES, EEP).
+
 - `available_in`: availability of that feature in GitLab:
  - For Community Edition, use `[ce, ees, eep]`
  - For Enterprise Edition Starter, use `[ees, eep]`
  - For Enterprise Edition Premium, use `[eep]`
- `documentation_link`: use to insert a link to the documentation.
-Required for the top feature, optional for primary and secondary features.
- `documentation_text`: use to customize the text for `documentation_link`.
-Required for the top feature and optional for primary and secondary features.
+
+#### Reference link (documentation, webpage, etc)
+
+Provide a reference link to the feature whenever possible. It can be, in this priority order:
+
+- A **feature webpage**, when available
+- A **feature documentation** link, when available
+- A **feature-related documentation** link, when both above are not available.
+
+As follows:
+
+- `documentation_link`: use to insert a link to the documentation, or, when available, link preferably to the feature webpage (e.g. Issue Boards, Cycle Analytics, Pages, Geo).
+  - `documentation_link` is required for the top feature and optional for primary and secondary features.
+- `documentation_text`: use to customize the text for `documentation_link`:
+  - If you don't use `documentation_text` at all, the fallback is "_Read through the documentation on `feature name`_". When the documentation link corresponds to the feature name, simply opt for omitting `documentation_tex` and using the fallback.
+  - Whenever the feature name doesn't match the feature documentation, use the `documentation_text` entry to adjust the text. E.g., if the feature name is "Improved Pipeline Graphs", and it links to the pipelines doc, `documentation_text: Read through the documentation on Pipelines`.
+  - Whenever you link to a webpage or anything rather than GitLab's documentation, use "Learn more about X: `documetation_text: Learn more about Feature Name`. E.g., if the feature name is "Improved GitLab Pages UX", `documentation_link: '/features/pages/'`, `documentation_text: Learn more about GitLab Pages`
+  - `documentation_text` is available for all feature blocks that include `documentation_link`.
+
+#### Illustration (images, videos)
+
 - `image_url`: link to the image which illustrates that feature.
-Required for primary features, optional for secondary features, n/a for top feature.
+Required for primary features, optional for secondary features and top feature.
 - `image_noshadow: true`: if an image (`image_url`) already has shadow
 the entry `image_noshadow` will remove the shadow applied with CSS by default. Optional.
+- `video`: when present, overrides the image and displays the linked video instead. Use the [link for embed videos](/handbook/product/technical-writing/markdown-guide/#videos). Available for primary features only. For all other blocks, add it into the description entries.
+
+Check the section **Adding Content** > [Illustrations](#illustrations) for more information.
+
+#### Feature Description
+
 - `description: |`: add the feature's description in this entry.
 Make sure your cursor is in the line below the pipeline symbol `|` intended once.
-All `description` fields fully support
+All `description` fields fully supportn
 [markdown](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/),
 the only thing you need to be worried about is respecting the indentation.