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: title, category, tags, iconSlug, permalink, alternate_urls, versionCommand, releasePolicyLink, releaseImage, changelogTemplate
2. Formatting: releaseLabel, LTSLabel, eolColumn, eolWarnThreshold, activeSupportColumn, activeSupportWarnThreshold, releaseColumn, releaseDateColumn, discontinuedColumn, discontinuedWarnThreshold, extendedSupportColumn, extendedSupportWarnThreshold
3. Product identifiers (identifiers)
4. Auto update configuration (auto)
5. Release cycles (releases - each release is separated by a blank line): releaseCycle, releaseLabel, codename, releaseDate, lts, support, eol, extendedSupport, discontinued, latest, latestReleaseDate, link

Some rules on individual fields:

• Dates (such as releaseDate) must never be quoted.
• Versions and cycles must always be quoted (double quotes).
• Version ranges with space surrounded dash, e.g. 2 - 5
• Version list separated with comma and space, e.g. 2, 4 - 7, 9
• changelogTemplate must be on one line, between double quotes if it's containing a liquid expression.

Text

Some rules regarding the markdown description:

• Keep Product Description limited to the first blockquote.
• Try to keep line length at 100 characters maximum.
• 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).
• Do not use <abbr>, use the following syntax *[<acronym>]: <title> (put at the end of the file). With this syntax you don't have to repeat the definition multiple times.

Tone and Text

• The text should be written in neutral-third-party using the present tense. endoflife.date is a third party, so avoid using first-person writing. "We support each major version for 3 months" is incorrect, prefer "each major version is supported for 3 months".
• Prefer strong phrasing (will, is) over weak ones (could, probably, will be).
• Avoid general guidance (such as installation instructions). Some specific guidance that might be helpful is good (such as finding out the release cycle for a product).
• Do not use the future-tense, unless talking about a future change (such as future releases, or release policy changes happening in the future). "Each version will be supported for 3 months" is bad, use "each major version is supported for 3 months. However, "Starting from v23 (due August 2024), each release will be supported for 6 months" is fine. Once the future change is live, revert to present tense: "Each release is supported for 6 months".
• Avoid mentioning older release policies that only apply to EOL cycles ("Prior to v3, only a single release was supported"). In general, focus on supported releases.
• Some guesswork is okay (such as guessing future release dates, and sometimes support dates).