With the update to the tagging feature, tag wikis have really come front and center. What are the guidelines for editing them? What info should go in there? What are some good examples of existing tag wikis?


Jeff Atwood outlines a number of important factors for tag wikis on the SE Blog.

  1. The excerpt is the elevator pitch for the tag. You only have ~500 plain text characters for the excerpt, so don’t feel obligated to cover everything in it! Save that for the 30,000+ character Markdown tag wiki. The excerpt should define the shared quality of questions containing this tag — boiled down to a few short sentences.
  2. Avoid generically defining the concept behind a tag, unless it is highly specialized. The “email” tag, for example, does not need to explain what email is. I think we can safely assume most internet users know what email is; there’s no value in a boilerplate explanation of email to anyone.
  3. Concentrate on what a tag means to your community. For “email” on Server Fault, mention the server aspects of email including POP3, SMTP, IMAP, and server software. For “email” on Super User, mention desktop email clients and explicitly exclude webmail, as that would be more appropriate for webapps.stackexchange.com.
  4. Provide basic guidance on when to use the tag. In other words, what kinds of questions should have this tag? Tags only exist as ways of organizing questions, so if we don’t provide proper guidance on which questions need this tag, they won’t get tagged at all, rendering the tag excerpt moot. Think of it as a sales pitch: in a room full of tags screaming “pick me!”, what would convince a question asker to select your tag?
  5. Some tags are common knowledge. Most tags require a bit of explanation in the excerpt, even if it’s only 3 or 4 words. But if the tag is common knowledge — that is, if you walked up to any random person on the street and said the tag word to them, and they would know what you were talking about — then don’t bother explaining the tag at all. Stick to usage of the tag within your community in the excerpt.

A lot of the tags in our community are or are bordering on common knowledge, and the focus should be largely on how they are used within our community. For example, the tag currently has the following excerpt and wiki:

(Excerpt) Questions about pasta, a dish originally from Italy consisting of dough made from durum wheat and water.

(Wiki) Pasta is a dish originally from Italy consisting of dough made from durum wheat and water, extruded or stamped into various shapes and typically cooked in boiling water.

I think we can safely assume that most participants on a cooking site will know what pasta is. The important question is, which questions about pasta are on topic, and when should the tag be used? A better excerpt wiki might be:

(Excerpt) Questions about the make, manufacture, preparation, and cooking of all types of pasta, including traditional durum wheat, whole wheat, and gluten-free.

(Wiki) This tag covers Italian and American styles of pasta either made from wheat or intended to simulate the flavor/texture of traditional Italian wheat pasta. Similar products from other parts of the world, such as Japanese Soba or Udon, are more traditionally called "noodles" and should be accompanied by the tag instead.

The tag wikis should help to define what is in or out of scope for the site and guide users in the proper use of tags. The tag excerpt is particularly important in this aspect as it is now visible when asking a question.

Some good existing examples of tag excerpts are:

  • - Questions on selecting, maintaining, and using cooking tools and equipment.
  • - Questions about the culinary uses of products that are normally discarded or used in non-culinary applications.
  • - Methods, techniques, and quality/safety concerns around the freezing of various foods.

Tag wikis that have a good overall explanation of the usage of the tag on the site include:

Community Wiki. Please add examples of good tag wiki excerpts and bodies or guidelines for editing tag wikis.

  • I added some examples and also tried to give a concrete example of a current bad tag and how to improve it. Let me know if you disagree...
    – Aaronut
    Aug 9 '11 at 23:17
  • Thanks, I was hoping you would weigh in. Good examples / counter-example.
    – yossarian
    Aug 10 '11 at 13:59
  • 1
    excellent guidance; so many sites fall into the "explain what this tag means" trap and fail to explain the most crucial part, when to use the tag. Aug 12 '11 at 1:36

I'll give some general guidelines as we use for the Network as a whole. I don't see much need to go past these, but if there's something special that you find useful and advantageous to adhere on to within this site specifically top of this, then it's welcome fully. ♪

A tag wiki is divided in two portions - the excerpt and the body. Each has its own purpose.

The excerpt is the entrance to the tag. It has two potential purposes - to explain what the scope of the tag is, and to define the term it represents. It also needs to accomplish this with succinctness. Which one you focus on depends on how obvious either purpose is, and which one is more important. For example, is pretty obvious as to what Coffee is, so the excerpt should concisely wrap up what actual coffee-based matters are appropriate for the tag. Time shouldn't be wasted on defining any common term. Comparatively, is somewhat vague as a term, and the existing excerpt does well to point out what its intended usage is and what the term implies.

The body, then, works to clarify in better detail the utility or the guidance as to what the tag is for. Whereas the excerpt points out the general scope, the wiki body is an excellent place to illustrate the kinds of questions that you would ask. Again, does it well, naming a quick list of example question types. It also highlights another useful bit, which is conflicts/relationships with other tags. If a tag might be confused for other tags, or if it is related to other tags in some fashion (such as a set of flags dealing with different portions of the same concept), then it is helpful to point out these items in the tag wiki body.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .