As the title says:
What are tag wikis, and how do I write a good one?
1 Answer
What is a tag wiki?
Each tag on Stack Exchange has two pieces of user-editable content associated with it:
a short tag wiki excerpt of up to about 500 characters of plain text, and
a full tag wiki page describing the tag in more detail.
The excerpt is the "elevator pitch" for the tag, and is shown in many places where the tag is used. However, its length is limited, and it cannot include Markdown. The full tag wiki looks and works very much like a question or an answer, and supports full Markdown syntax.
What is the purpose of tag wikis?
The main purpose of the tag wiki excerpt is to tell people what the tag should be used for. It is shown to people asking a question when they type the tag name (or part of it) in the tag entry box. Without an excerpt, people have to guess whether the tag applies to their question based on the name alone, which can lead to confusion if the name might apply to several different things.
The purpose of the full tag wiki is to provide additional information that does not easily fit in the excerpt. This can include:
- a more detailed explanation of how to use the tag,
- general background information on the subject,
- a list of frequently asked questions on the topic, and/or
- links to useful external resources, like Wikipedia pages or official documentation.
Where are tag wikis shown?
The tag wiki excerpt is shown:
- at the top of the list of questions tagged with the tag,
- in the list of all tags on the site,
- in the popup that appears when you hover the mouse over the tag, and
- in the menu of available tags shown when a user is adding tags to a question.
A "learn more" link, shown alongside the excerpt, points to the "info" tab for the tag, which shows the full tag wiki. This is also the place where both the excerpt and the full tag wiki can be edited.
If the tag has no full tag wiki, but does have an excerpt, the excerpt is shown in the info tab instead.
How do I write a great tag wiki?
Start with the excerpt. That's the part of the tag wiki that users will see first, and the only part that most users will see at all. The excerpt should define, in a few short sentences, what questions using the tag should be about.
Sometimes, however, it's easier to start by writing a one or two paragraph description of the tag for the full wiki, without having to worry about length constraints or lack of Markdown, and then condense this down to the excerpt. That's a perfectly fine way to work, too.
Don't copy content written by others without attribution. Often, it's tempting to just copy a definition of the tag subject from, say, the Wikipedia article on the topic. This can be acceptable, if the material you copy is either licensed under a free license compatible with ours (like Wikipedia is) or short enough to qualify as fair use, but only if you attribute it properly.
For short verbatim quotations, the preferred way is to use explicit blockquotes, like this:
According to the FooBar 5.1 documentation:
"The Frobnicator is a new feature in FooBar 5.1 that allows concurrent execution of multiple non-deterministic Boojums on linked FooMesh nodes."
If you base your tag wiki on text from a freely licensed source like Wikipedia, it's also acceptable to indicate this using a footnote, such as:
This tag wiki incorporates material from the Stack Overflow article on Wikipedia, written by Wikipedia users Michael B. Trausch, Jonik, Svick and others, used under the terms of the CC-By-SA 3.0 license.
However, note that content copied straight from Wikipedia rarely makes a good tag wiki. Tag wikis are not encyclopedia articles, and defining the subject is not their main purpose. Typically, turning a Wikipedia article into a great tag wiki requires extensive editing, to the point where it may well be easier to just write the tag wiki in your own words from the beginning.
Remember that the full tag wiki is not just an appendix to the excerpt. It should stand alone as a detailed description of the tag, and should include all the information present in the excerpt.
On the Stack Exchange blog, Jeff Atwood writes:
"Here’s a few words of advice on writing tag wiki excerpts:
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.
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.
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.
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?
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."