Skip to content

Latest commit

 

History

History
143 lines (122 loc) · 4.05 KB

kb-labels-guide.md

File metadata and controls

143 lines (122 loc) · 4.05 KB

This document provides guidelines for adding labels to articles in the Support Knowledge Base for Commerce repo. Labels (also called tags) improve searching experience in the Support Knowledge Base for Commerce. Labels are added in the "labels" field in metadata section of an article file, separated by commas, no space between a comma and the next label. See [../../.github/CONTRIBUTING.md#metadata] for details.

General provisions

For each article add the following label types:

  • Label(s) for product(s). (required)
  • Label(s) for versions affected. (required, except general support related articles)
  • Label for content type. (required)
  • Labels for major tech component.(if applicable)
  • Labels for process/functionality being troubleshooted/described. (if applicable)
  • Labels for the issue being fixed/described. (if applicable)

See the sections below for detailed recommendations on how to define labels for each of these labels types.

Labels for products

Product name Label
Adobe Commerce (all deployment types)  "Adobe Commerce"
Adobe Commerce on our cloud architecture  "Adobe Commerce,cloud"
Adobe Commerce on-premise "Adobe Commerce, on-premise"
Magento Business Intelligence (MBI) "Magento Business Intelligence,MBI"
B2B for Adobe Commerce "B2B"
PWA for Adobe Commerce "PWA"
Venia storefront project "Venia"
Quality Patches Tool, QPT "Quality Patches Tool,QPT patches"

Labels for products versions

  • Add a separate label for each version of Adobe Commerce. Example: "2.3.7"
  • Don't add labels for intervals. That is, if 2.3.0-2.3.5 if affected, add: "2.3.0,2.3.1,2.3.2,2.3.2-p2,2.3.3,2.3.3-p1,2.3.4,2.3.4-p2,2.3.5-p1,2.3.5-p2" NOT "2.3.0-2.3.5"
  • Don't add labels with .x. Example: "2.3.x"

Labels for content type (based on category)

Category Label
Best Practices "best practices" (not "Best Practice" nor "best practice")
Troubleshooting "troubleshooting"
How to "how to"
FAQ "FAQ"

Labels for major technical components

  • Use capitalization according to the component official naming.
  • Do not use synonyms, one label for one component.
  • One word labels are preferable, but if component name contains several words - use several words. Do not add issue descriptions. That is, put "Elasticsearch" instead of "Elasticsearch problems".
  • If the content is relevant for a particular version of the component only - add a label containing name + version.
    Example: "Elasticsearch 5". If it is relevant for several particular versions - add several labels of this type. Example: "Elasticsearch 5", "Elasticsearch 6". When relevant, use "x" for multiple versions. Example: "Elasticsearch 2.x"

Examples:

  • "Elasticsearch"
  • "New Relic"
  • "Web Setup Wizard"

Labels for process/functionality being troubleshooted/described

  • Use low case, with exception of proper nouns.
  • Do not use synonyms, one label for one entity.
  • One word labels are preferable. Do not add issue description. That is, put "database" instead of "database crashes".

Examples: 

  • "database"
  • "cron"
  • "deployment"
  • "mass update".

Labels for the issue being fixed/described

  • Use low case, with the exception of proper nouns.
  • Do not use synonyms, one label for one entity.
  • One word labels are preferable. Do not convert an error message to a label.

Examples:

  • "site down"
  • "500 error"
  • "stuck cron".