Wiki: User Experience Guidelines

Wiki: User Experience Guidelines

The User Experience Guidelines exist as an effort to establish basic consistencies across TechNet Wiki. The guidelines are manual (you have to make the changes yourself), and a goal of creating manual guidelines is to eventually turn some of them into automatic
guidelines (that occur automatically through tools) in order to reduce editing and communication around following the guidelines.

"How Do I..." (This is often used to teach a standard or expectation to users, which might just come across as confusing or inconsistent.)

Gerunds, such as "Restoring a File."

"How to..." (This can be confused with "How To" articles that could give users preconceived notions of procedural, step-by-step content.)

The one gerund exception is when the gerund acts as a noun.

EXAMPLE: "SSRS Troubleshooting: Installation"

The goal is to risk vagueness and focus on the verbs and nouns to explain the type of content. For example, "Sign up a User" should tell you that an article is more procedural than "Design a Deployment Process."

By risking vagueness, we gain consistency, professionalism, and clarity, focusing on the content of what we're presenting, rather than trying to teach them what our additional words mean about the content (such as trying to differentiate "How to Sign up
a User" from "Designing a Deployment Process"--the result is just that we look inconsistent).

EXAMPLE: "Restore a File"

BAD EXAMPLES:

"How Do I Restore a File"

"Restoring a File"

"How Should I Restore a File"

Nouns/Subjects

Use only the noun and adjectives.

Do not include:

"A few tips on..."

"How to Understand..."

"Introduction to..."

"Understanding..."

"About..."

"... Overview"

EXAMPLE: "SQL Server 2008 R2"

BAD EXAMPLES:

"Understanding SQL Server 2008 R2"

"A few tips on SQL Server 2008 R2"

"How to Understand SQL Server 2008 R2"

"Introduction to SQL Server 2008 R2"

"About SQL Server 2008 R2"

"SQL Server 2008 R2 Overview"

See
Page Layout below. The overview/conceptual articles give the high-level perspective and drill down to a digestible level. Further drilling should be done by creating more articles that are specific to the topic.

For example, instead of using titles like "Introduction to SQL Server" and "SQL Server for Experts", you start every overview/conceptual article with the introduction and drill down to a digestible level. Then you specify what the expert topics are and
link out to them.

First person

Avoid first-person articles in your titles like "I" and "me"

EXAMPLE: "How to Install SQL Server"

BAD EXAMPLE: "How I Installed SQL Server"

Questions

Avoid questions in the title.

Do not include:

"Should I..."

Product name prefixes

You can optionally add the acronym or an abbreviated version of your product name before many articles in order to clarify the technology that the article is for.

EXAMPLES:

"FCS: MOM Client States"

"DAX: Statistical Functions"

"Windows 2008: ..."

"SCCM 2012: ..."

Include "Wiki: ..." before any article title about TechNet Wiki.

EXAMPLES:

"Wiki: User Experience Guidelines"

"Wiki: Management Portal"

Punctuation and symbols

Do not use symbols such as:

Question marks (?)

Ampersand (&)

After starting with a product name, use a colon (:) instead of a dash (-).

Non-English Languages

For non-English articles in the English language Wiki, put the language code in parenthesis at the end of the article (after a space).

EXAMPLE:

SQL Server (it-IT)

Also add the language code as a tag (without the parenthesis).

EXAMPLE:

Tags: it-IT

This is for filtering in searches, to make it easier to identify what language the article is written in, and to make it more obvious to know which articles might need to be migrated to a new language instance of TechNet Wiki.

Do not use "(en-US)" in English titles. It is the English wiki, and eventually each language might have its own wiki.

Note that you do not need to use the language codes for non-English Wiki instances. For example, in the Brazil (Portuguese) version of TechNet Wiki, you do not need to put the "(pt-BR)" code in the title or the tags. We also have Russian and Chinese versions
of the Wiki.

Font and Design

Although all these guidelines should be followed, the highest priorities are the font type, font size, and to stick with a form of black color throughout the article. These three guidelines are important because they impact the cohesiveness, branding, and consistency
of the look and feel of TechNet Wiki.

Page Layout

Stub pages

Stub pages are pages with no useful content added yet. They exist to remind you and the community fill out the content.

Once useful content is added, remove the "stub" tag from the article's tag list.

Place this text at the top of the page: This article is a stub. Fill in the missing content.

After the stub text at the top, you might want to include a bulleted list of possible topics, sections, or lists in the topic.

Add the "stub" tag to the article. We recommend that you don't include many other tags, because it is better if stub articles are not too easy to find (because you want contributors to find them more often than readers-only).

When the article has some useful content, remove the stub text and the stub tag. If you feel the article still isn't complete, use the "Needs Work" tag and include a statement that the article needs more work.

Sections

Introduction section at the top

This should be at least one sentence, but make it no more than two short paragraphs.

If this section is too long, it will make it hard for the reader to notice the page TOC.

TOC section

This is the page's table of contents (TOC).

Add this section below the introduction section (which is between one sentence and two short paragraphs).

Below that text, include the [TOC] tag (this way the TOC is created for you automatically).

Pull it into a Portal page if >10 links. If you have over 10 links in this section, create a new Portal page on the topic ("<Product Name> Portal") that includes only links to other Wiki articles on the topic.

See Also section

Link to domain parent articles and related articles in TechNet Wiki (such as an Overview article or a Portal that lists all the TechNet Wiki articles about that technology).

This section should exist in all articles, if possible.

This is a link list at the bottom of an article.

Place a horizontal line rule above and below this section.

Limit this section to about 10 links. If you have over 10 links that pertain to this article, create a separate portal page that links to Wiki-articles that pertain to a common subject.

Additional Resources section

These are the external links, including links to Microsoft and TechNet sites that are non-Wiki.

This is a link list at the bottom of an article.

Place a horizontal line rule above and below this section.

Pull it at the bottom of a Portal page if >10 links.

TechNet Resources section

This list is specific to TechNet resources found on the topic.

This is a link list at the bottom of an article.

Place a horizontal line rule above and below this section.

Pull it into a Survival Guide page if >10 links.

TechNet Library section

This list is specific to TechNet Library pages found on the topic.

This is a link list at the bottom of an article.

Place a horizontal line rule above and below this section.

Pull it into a Survival Guide page if >10 links.

"Credits section

You should give credit to the original author.

Make sure you have the author's permission to publish their work on TechNet Wiki.

Include a section titled "Credits" at the bottom.

Include a line before the list sections at the bottom.

Use this format:

This article was originally written by <original author>.

Use italics on the entire line.

Bold the names or link them to the profile.

You can also link to the author's source page, such as a blog or forum thread.

If you rewrote the article based on someone else's article, get permission, and then use this format:

This article is based on information from <article reference> written by
<original author>.

References section

Use this section if you pulled source material and ideas from other sites, blogs, or forums. Make sure you have permission from authors to use their material.

This is a link list at the bottom of an article.

Place a horizontal line rule above and below this section.

Other Languages section

If the article has been translated into at least one additional language, add an "Other Languages" section to the bottom of the English article, and add the "has Other Languages" tag to the English article only (do not add the tag to articles in other languages;
they should have similar tags unique to their languages).

In a bulleted list in this section, list links to all the other articles in different languages.

Headers

Use the H1 paragraph style for all your top-level section titles.

Then use H2 for the next level, and so on.

This creates consistency across the articles and allows the TOC system to work better.

General

In-line Wiki links

In the introduction section, include a link (when possible) to the parent topic.

Signatures, Credit, and Personalization

As Ana mentioned
in this blog post, Wikipedia has this to say about signatures: "When editing a page, main namespace articles should not be signed, because the article is a shared work, based on the contributions of many people, and one editor should not be singled
out above others." - Wikipedia: Signatures

The exception we make, is that we allow the Credits section (see
"its Section" in "Layouts" above).

Do not use first person

Use third person instead.

If you're pasting from your blog, where you use first person, you and the community should change it to third person instead.

EXAMPLE:

This article informs you how to set up your computer.

BAD EXAMPLE:

Now I'm going to show you how to set up your computer.

Do not use greetings

Do not use a personal or any other signature

No personal picture

As mentioned earlier "articles should not be signed, because the article is a shared work, based on the contributions of many people"

No contact details

Put your contact details in your Technet/MSDN profile

Avoid personal commentary

Remove any unnecessary personal commentary that might have been in the blog post.

EXAMPLE:

This article informs you how to set up PowerPivot for SharePoint.

BAD EXAMPLE:

So I was taking a shower last night, and that's when it occurred to me (I do all my best thinking in the shower), that I should show you how to set up PowerPivot for SharePoint!

We can use personal commentary in a blog post instead (including Wiki Ninjas blog). Just leave a comment here to make a request.

Turn personalization and opinions into sections with lists

For example, if you are explaining why you wrote the article, instead you can turn it into a section about the values of the article and then list them out.

For example, if you want to give your personal opinion on a topic that people disagree about, you can make sections on both sides of the discussion and list the reasons for both sides.

However, we want to give you credit for your work... We provide five ways for you to receive credit for your contributions in TechNet Wiki:

FIRST PUBLISHED BY and LAST REVISION BY profile info and links

This is the section on the upper right, which tells you who published and revised the article

It includes your name

Your avatar/picture

Your status role (such as Microsoft, MCC, and MVP)

The date you created or modified the article

Link to your profile

The Hover Card feature where the reader can hover the mouse cursor over your name and see your Recognition Points, total Achievement Medals, and the last three Achievement Medals you've earned

HISTORY tab's REVISION AUTHOR list and Comments

Your name

Link to your profile

The Comments also include your photo/avatar, and the Hover Card features

The Credits section

You should give credit to the original author.

Make sure you have the author's permission to publish their work on TechNet Wiki.

Include a section titled "Credits" at the bottom.

Include a line before the list sections at the bottom.

Use this format:

This article was originally written by Jayant.

Use italics on the entire line.

Bold the names or link them to the profile.

You can also link to the author's source page, such as a blog or forum thread.

Tags

You can create a personal tag for the original author or major contributor, to track all the articles that the person has written.

Links and Accessibility

Follow these guidelines in order to provide a complete story of Wiki navigation and accessibility. We might try to automate more of these features in the future in order to require less manual work and maintenance.

Tags

To make an article easier to discover using the wiki search, include tags that are relevant to the topic discussed in your article. For example, an article that discusses using SQL Server Express with PHP should be tagged with the 'SQL', 'SQL Express',
and 'PHP' tags.

Commas

Divide each tag with a comma and a space. For example, "SQL, SQL Express, PHP, Needs Work"

Casing

When possible, use title casing, such as "Troubleshooting Guides".

Always use proper casing on product names, such as "SharePoint 2010".

EXAMPLE:

PowerPivot

BAD EXAMPLE:

powerpivot

Note that we know many tags have been "ruined" in the sense that the first person entered the casing incorrectly and we're now stuck with it. We have a feature request to update tag casing.

Be concise

Try to limit the tags to one, two, or three words.

Spacing

Use a space between words instead of putting them together. For example, use "Needs Work" instead of "needswork".

Because you divide tags by commas, you don't need to use quotes around multiple words.

Specific tags

Delete--Use this tag when you think an article should be deleted. Then contact Wiki administrators for discussion.

Needs Work--Use this tag when your article includes some information (so it is not a stub) but not enough to be a useful article.

Stub--Use this tag only (and no other tags) when no useful content exists.

Note that you don't need to add language codes to tags when the article is in a Wiki dedicated to that language. For example, you don't need to add the "ru-RU" tag to articles in the Russian instance of TechNet Wiki.

However, we are adding the "en-US" tag to all English articles. This allows us to quickly filter out all non-English articles in tag results.