Skip to content

Style Guide

BiNZGi edited this page Nov 17, 2023 · 5 revisions

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).
Clone this wiki locally