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.

In this article:

Table of Contents

 

Titles and Subtitles

The title of the article determines the URL of the article. For example, an article is titled "Wiki: Style Guide", which results in a URL of http://social.technet.microsoft.com/wiki/contents/articles/wiki-style-guide.aspx. Note that spaces become '-' and characters such as ':' are ignored when creating the URL for an article.

For more details, see the Wiki Title Guidelines.

  • Casing
    • Use title capitalization rather than sentence capitalization.
      • EXAMPLE: "User Experience Guidelines"
      • BAD EXAMPLE: "User experience guidelines"
    • Do not use all caps.
      • BAD EXAMPLE: "USER EXPERIENCE GUIDELINES"
    • Capitalize the first letter of the word after a hyphen.
      • EXAMPLE: "Scenario-Based Instructions"
      • BAD EXAMPLE: "Scenario-based Instructions"
    • When quoting an error message in a title, you can use sentence casing (or whatever is in the error message), and enclose the message in quotations.
      • EXAMPLE: Analysis Services Troubleshooting: 10038 - "A timeout occurred. The interface cannot be enabled."
    • Make "to" and "with" lowercase.
      • EXAMPLE: "How to Install Windows 8"
      • BAD EXAMPLE: "How To Install Windows 8"
  • Verbs 
    • Use present tense instead of:
      • "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
    • For keeping a consistency in the Wiki, it's highly advised to 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:
      • "Microsoft Virtualization Technologies: List of Microsoft Support Knowledge Base Articles Related"
      • "Microsoft Intune: List of Public Microsoft Support Knowledge Base Articles "
      • "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 (-).
      • EXAMPLE: "AD FS 2.0: How to Restore Your Session"
      • BAD EXAMPLE: "AD FS 2.0 - How to Restore Your Session"
    • Don't use a period at the end of the title.
  • Commas

 

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.
  • For a list of all the language codes and for links to all the articles for each language, see the Non-English Language Title Guidelines.
  • 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.

 

↑ Return to Top

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.

Default

  • By default, the editor uses:
    • Font type: Segoe UI
    • Font size: 12-point font size
    • Font color: black
  • You don't need to code these default fonts, sizes or colors.

Guidelines

  • Use black throughout the article, including section headers.
    • Use default color settings, do not force white background and/or black text.
  • Code
    • Use Courier New, 11px
  • Capitalization
    • Capitalize the first letters of the name of a dialog box or window.
    • Capitalize the first letters of text as it appears in the user interface (UI).
    • Use all caps on NOTE and EXAMPLE.
  • Italics
    • Use italics for emphasis and text quotes
  • Bold
    • Use bold on UI terms only (text as it appears in the product's interface).

    • EXAMPLE:

      • Click File.
    • Use bold on NOTE.
    • EXAMPLE:
      • NOTE: Do not format your hard drive.
  • Underlines
    • Do not use on headers, EXAMPLE, or NOTE.
  • Notes
    • Use all caps. For example:
      • NOTE:
    • Use a colon after it and not a dash.
    • Bold it.
    • If you have more than one note, use "NOTES:" and then include a bulleted list below it.
  • Images
    • Use smaller images so that smart phone users can see them.
    • You can upload a larger image and then resize it to a smaller size.
  • Tables

 

↑ Return to Top

Pictures

  • Respect privacy and copy right regulations
    • Make sure you own the pictures or you have the right to (re)publish them
  • Do not link pictures from blogs, external sources, other articles or other 3rd party source
  • Upload pictures on MSDN/Technet Wiki

 

↑ Return to Top

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).
    • In your article, use the appropriate Heading paragraph style for the section headers (for example, Heading 1).
    • Make sure you use the H1 header for your top-level sections, H2 for the next level, etc. This is for consistency and to allow the TOC system to work properly.
    • The TOC will be created automatically based on the Heading paragraph styles.
    • For more information about creating a TOC, see How to Automatically Add a Table of Contents (TOC) to Your Wiki Article.
  • <Product Name> Wiki Pages section
    • This section is optional, and it should be used in Overview articles.
    • 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 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.
    • Include a hyperlink in the term of the text.
    • EXAMPLE: "Data Analysis Expressions is a new language used in PowerPivot for Excel."
  • In-line external links
  • Spaces between paragraphs
    • Include one white space between paragraphs.
  • Horizontal line rules
    • Use Horizontal Line Rules to divide every H1 section.
    • Use Horizontal Line Rules to divide up the See Also, External Links, Community Resources, References, TechNet Resources, and TechNet Library sections.
    • To place a Horizontal Line Rule, click the Insert Rule button on the right side of the tool bar.
  • 'Return to Top' links
    • Include the arrow graphic (you can copy and paste it from this article).
    • Use the text, "Return to Top"
    • Link back up to the very top of the article (and not just the TOC).
    • Include this at the bottom of each section, above the horizontal line rule.
    • EXAMPLE: ↑ Return to Top
  • Different page styles/templates
    • Overview articles
    • Troubleshooting articles
    • Instructional articles
    • Portals
    • Survival Guides
    • Stubs

 

Note
We might want to adopt more formatting techniques from this great article from Mary Lingel.

 

↑ Return to Top

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:

  1. 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
  2. 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
  3. 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.
  4. Tags
    • You can create a personal tag for the original author or major contributor, to track all the articles that the person has written.
    • EXAMPLE: The "Ed Price" tag
  5. Comments
    • The Comments section is at the bottom of the page (every page has a comments section in the Article tab, at the bottom of the page).
    • Leave a comment to answer questions or to include personalization, such as how the article idea came to you in the shower.  

 

↑ Return to Top 

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.

The related topic of Cross-Linking is discussed in Wiki: Cross-Linking

 

Note
This section includes only brief explanations. For full guidelines and details, see the appropriate bullets in the Page Layout section above.

 

  • Article table of contents
    • This is the "In this article" section under the introduction section.
    • See Page Layout above for detailed instructions on how to create this section.
  • 'Return to Top' links
    • These links exist at the bottom of every section (above the horizontal rule) and link back up to the very top of the article (and not just the TOC).
  • In-line links
    • In the introduction section, include a link (when possible) to the parent topic.
  • <Product Name> Wiki Pages section
    • Pull it into a Portal page if >10 links.
  • See Also section
    • This is a link list at the bottom that links to domain parent articles (and related articles) in TechNet Wiki.
  • Other Resources section
    • These are the external links, including links to Microsoft and TechNet sites that are non-Wiki.
  • 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.
  • Other Languages
    • This section lists all the other translations for your article. 
    • This should be last section.
    • Make sure all the languages are listed in this section for each of the different languages. It makes it easy to navigate between the different languages.
  • Portal guidelines
    • If you have 10 links or more to TechNet Wiki articles, create a separate portal page that is made up of TechNet Wiki articles only.
    • You can include a Community Resources section if you have < 10 links.
  • Survival Guide guidelines
    • If you have 10 links or more to non-TechNet Wiki articles, create a separate survival guide / community resources page.
    • Use "Survival Guide" as the name instead of "All Resources", "Community Resources" or "Resources". 
      • For example, use "PowerPivot Survival Guide" instead of "PowerPivot Resources".

 

↑ Return to Top 

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.
    • Wiki--Use this tag when the article is about TechNet Wiki.
  • Language tags
    • Add the language code as a tag (without the parenthesis).
    • EXAMPLE:
      • Tags: it-IT
    • For a list of all the language codes and for links to all the articles for each language, see the Non-English Language Title Guidelines.
    • 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.

 

↑ Return to Top

Different Page Styles

This section requires more information.

 

↑ Return to Top

See Also

 

Other Languages