Tag Guidelines Template

Copy and paste this Tag Guidelines Template as the answer to a "How should we use tags?" question in Stack Overflow for Teams and tweak it based on your needs.

For best practices on developing a tag strategy and grooming process, read Best practices for tag lifecycle management: Tag strategy and grooming.

Tags are keywords or phrases that categorize our knowledge so that it's easier to ask questions and get answers. Since they’re fundamental to how knowledge is shared in Stack Overflow for Teams, we’ve put together the following guidelines for using them.

Tag basics

Formatting

Tags are always lowercase and use hyphens instead of spaces. For example, a Google Analytics tag would be formatted like this: [google-analytics].

Topics

For guidance on what types of tags you should use and create, reference the following topics:

  • Project names
  • Lines of business
  • Product lines
  • Technologies
  • Programming languages
  • Tools

Excerpts

Every tag should have an excerpt since it helps other users understand its purpose. At a minimum, the excerpt should include basic information about when to use the tag. It can also point to a channel on Microsoft Teams or Slack that gets notified when questions are asked using the tag.

Here’s a good example of an excerpt from Stack Overflow’s [android-studio] tag. The community makes it clear that the [android-studio] tag should only be used for Android Studio questions and that more general Android questions should use the [android] tag.

Naming convention

You should only hyphenate tag names if they require a space or cover a subtopic of a broader topic. A good example would be tags for product lines: [product-a], [product-b], etc.

In some cases we prefer that you don't hyphenate tags for subtopics. For example, if we have a [security] tag and get a lot of questions about single sign-on, create an [sso] tag instead of a [security-sso] tag and ensure both the [security] and [sso] tags have clear usage guidance in their excerpts. When in doubt, consult an Admin before creating a new tag.

Acronyms

Acronyms can be used to name tags, but you should always consider whether or not it has different meanings to different teams. For example, an [ip] tag means “Internet Protocol” to our technology teams but “Intellectual Property” to our legal teams.

A good rule of thumb for all tags, but especially acronyms, is having a clear tag excerpt.

When and how to create a new tag

To prevent tag overlap, strive to use existing tags as much as possible and only create new ones for unique topics. If you do need to create a new tag, follow this process:

Use this section if you're on the Free or Basic plan

A tag cannot exist without at least one question where it can be applied. To create a new tag, either add it as you’re asking a relevant question or edit an existing question and apply the new tag retroactively.

Use this section if you're on the Business or Enterprise plan

To create a new tag, either add it as you’re asking a relevant question, edit an existing question and apply the new tag retroactively, or reach out to a site Admin or Moderator to have them add it.

When to merge and create synonyms for tags

Use this section if you're on the Free or Basic plan

Only site Admins can merge and create synonyms for tags. A tag should be merged when one tag is preferred over another. For example, the [productsuport] tag is both misspelled and formatted incorrectly. You can ask an Admin to merge it with a [product-support] tag to delete the misspelled tag and automatically apply the correct [product-support] tag to any corresponding questions.

Tag synonyms redirect users to the main tag you want to be used. For example, if you know that teams will tag support-related content with both [product-support] and [customer-support] tags and you want to only use [product-support] because it notifies the team’s Slack channel, ask an Admin to add [customer-support] as a synonym to redirect users.

Use this section if you're on the Business or Enterprise plan

Only site Admins and Moderators can merge and create synonyms for tags. A tag should be merged when one tag is preferred over another. For example, the [productsuport] tag is both misspelled and formatted incorrectly. You can ask an Admin or Moderator to merge it with a [product-support] tag to delete the misspelled tag and automatically apply the correct [product-support] tag to any corresponding questions.

Tag synonyms redirect users to the main tag you want to be used. For example, if you know that teams will tag support-related content with both [product-support] and [customer-support] tags and you want to only use [product-support] because it notifies the team’s Slack channel, ask an Admin or Moderator to add [customer-support] as a synonym to redirect users.

Who should be tag SMEs

Subject matter experts (SMEs) should be assigned to tags so they’re notified of new questions. SMEs are usually tech leads, systems admins, and product managers. If you think a tag should have a designated SME, follow this process:

Use this section if you're on the Free or Basic plan

Tell the person who you think should be the tag’s SME to watch that tag so they’re notified of new questions.

Use this section if you're on the Business or Enterprise plan

Ask an Admin or Moderator about assigning a Subject Matter Expert to the tag so that SME is notified of new questions and is recognized as the go-to person for that topic across the company.

When to create a Collection

This section is for customers on the Business and Enterprise plans only.

Tags should be used to group content vertically. Collections should be used to group content spanning multiple tags, time periods, or content types for a use case specific to your team.

For example, you can create a “PR Environments” collection to get new engineers up-to-speed on how to work with our pull request environments by including some content tagged with [kubernetes], [github], and [devx].

Collections also allow you to group and organize only a subset of questions for a particular tag. For example, you may want to include only introductory [kubernetes] questions that were asked when we first started using it in a “Kubernetes Fundamentals” collection.

What to read next