Style Guide

Structure

This applies to the product document structure (Front-Matter YAML for Metadata, and Markdown for the text).

Front Matter YAML

• Order of attributes (each block is separated by a blank line):
  1. Product level informations
  2. title / category / iconSlug / permalink / alternate_urls / versionCommand / releasePolicyLink
  3. changelogTemplate / releaseLabel / LTSLabel
  4. activeSupportColumn / releaseColumn / releaseDateColumn / eolColumn
  5. purls
  6. auto
  7. releases (each release is separated by a blank line)
• No use of <abbr> (prefer the following syntax *[<acronym>]: <title>).
• changelogTemplate on one line, between double quotes if it is containing a liquid expression (that may prevent the link to be split on multiple lines by latest.py - to be confirmed).
• No quotes around dates.
• Versions and cycles always inside double quotes.

Text

• Max line length in description: 100 characters (exceptions are OK for instance for lines ending with a long link).
• No links reference definitions, except if a link is repeated.
• Explain acronyms if it is not obvious or part of the product name (but try to avoid acronyms).
• Keep Product Description limited to the first blockquote.

Tone

TODO