The Wiki article Wiki: User Experience Guidelines is a great resource for making all TechNet Wiki articles more useful. A good example is the use of cross-linking to improve the user experience. It helps users navigate the Wiki and find the information they need without searching. It leverages the information we author and makes it more discoverable.



Portals

Portals are lists of links to TechNet Wiki articles in a given area or technology. Portals can have sections for general overview articles, a section for articles describing how to install, setup, and configure the technology or product, a section for troubleshooting, etc. A user can be guided to the level of detail they need. A TechNet Wiki portal should only have links to TechNet Wiki articles, unless it has a section for Additional Resources.

Portals serve as a table of contents for the TechNet Wiki. Instead of each entry referring to a page number, each entry is actually linked to a TechNet Wiki article. This allows users to easily navigate the TechNet Wiki to find the information they need. The following article is a Portal of Portals, linking to all of the portals in the TechNet Wiki: Wiki: Portal of TechNet Wiki Portals

The main Wiki page, TechNet Wiki, has links to 8 portals, each for a major technology area. These portals are:

These portals can link to additional portals for each individual technology. Each portal acts as a gateway to more detailed subjects. For example, the "Technologies Portal" above links to AD RMS Portal, which is the portal for that technology.

↑ Return to Top


Link to Parent Article

If a Wiki article has a parent main topic article, it should be linked in the introductory paragraph. For example, the article Active Directory: PowerShell AD Module Properties defines the concepts of default and extended properties exposed by the PowerShell AD cmdlets (like Get-ADUser and Get-ADComputer). The article links to others with more details about the properties exposed by individual cmdlets. One of these child articles is Active Directory: Get-ADUser Default and Extended Properties. This article includes a link to the first article (the parent article) in the opening paragraph. The parent article should also be linked in the "See Also" section of the child article. As another example, note that this article includes a link in the first sentence to Wiki: User Experience Guidelines.

 

↑ Return to Top


Table of Contents

In longer articles with several headings or sections we can use the automatic TOC (Table of Contents) feature to improve the usability of the article. Each entry in the TOC links to a heading in the article. It provides a quick overview of the topics covered, plus a convenient way to navigate to the information a user needs. For step-by-step instructions to add a Table of Contents, see this article: How to Automatically Add a Table of Contents (TOC) to Your Wiki Article

 

↑ Return to Top


Embedded Cross-Links

Terms and acronyms in an article can be linked to information that defines the concept. Rather than explaining what every term or acronym means in every article where it is used, we can define each term in one place and leverage this in other articles. An embedded cross-link can refer to an article dedicated to a full explanation of the term. Or it can link to an entry in a glossary where many definitions are collected in one article. Only the first usage of each term in an article should be cross-linked.

 

↑ Return to Top


See Also Section

We should encourage authors to include a See Also section in most TechNet Wiki articles. This section would contain links to other TechNet Wiki articles related to the topic in a bullet list. Some articles would go into the subject in more detail; others would be articles on similar topics.

NOTE: The See Also section should only link to TechNet Wiki articles. For links to other sources (Forums, TechNet Library, Blogs, etc.), please include those links in the Additional Resources section. 

↑ Return to Top


Steps to Create a Cross-Link

For purposes of this discussion, the article in which you are creating a hyperlink is referred to as the parent article. The link is a url (Uniform Resource Locator, or web address) to an article referred to as the target article.

You can copy a link from one article to another. Of if you cannot find a link to copy, use the "Hyperlink Manager" in the Wiki editor to create links. Highlight the text to be linked in the parent article, click the "Hyperlink Manager" button, and enter the url for the target of the link in the "URL" field.

Link to an Article

The easiest way to add a link to a Wiki article is to copy it from another article. The link can even be copied from a list of Wiki search results. For example, if the link you want already exists in the "See Also" section of an article, copy the link to your clipboard, then edit your article and past the link in the proper location.

You can also copy the link in the bread crumb trail at the top of an article. For example, to copy a link to this article, copy the title in the bread crumb shown in the rectangle in the image below:



Notice above that the url shows at the bottom of the display when you hover over the title in the bread crumb.

If you cannot find a link to copy, you will need to edit the parent article, enter the title of the target article in the editor, highlight the title, and click the "Hyperlink Manager" button. On the Hyperlink tab enter the url of the target article in the "URL" field.

It can help to have both Wiki articles open in separate tabs or instances of your browser. First copy the title of the target Wiki article (so it is on your clipboard). Then edit the parent Wiki article and paste this title in the appropriate location in the article. Now switch back to the target article and copy the url of the article. Switch to the parent Wiki article and click the "Hyperlink Manager" button so you can paste the url in the "URL" field. After you save the article, test the link to make sure it works as intended.

Link to a Heading in an Article

Instead of linking to the entire article you can link to a heading in the article (an entry in the Table of Contents). In this case paste the title of the heading in the target Wiki article into the parent Wiki article (or enter some other appropriate text). Switch to the target article and hover over the entry in the Table of Contents. Right click and select "Copy shortcut". For example, if you want to link to the section titled "Get-ADObject" in the article "Active Directory: PowerShell AD Module Properties",
the image below shows how you would copy the url from the Table of Contents:



Once you have the url on your clipboard, go back to the parent Wiki article, highlight the heading (or other string you entered), click the "Hyperlink Manager" button, and paste the url in the "URL" field. The url will be the url of the article, followed by the "#" character, followed by the anchor tag name assigned to the heading. For example, the url for the heading "Get-ADObject" in the article titled "Active Directory: PowerShell AD Module Properties" will be as follows:

http://social.technet.microsoft.com/wiki/contents/articles/12031.active-directory-powershell-ad-module-properties.aspx#Get-ADObject

In this case, the anchor tag name, "Get-ADObject", matches the name of the entry in the Table of Contents, but this is not always the case. In fact, some characters are not allowed in anchor tag names, such as spaces. Any spaces in a heading will be replaced by underscores, such as "Extended_Properties" in this example:

http://social.technet.microsoft.com/wiki/contents/articles/12031.active-directory-powershell-ad-module-properties.aspx#Extended_Properties

Link to a Term in an Article

You can also create a link to any term or acronym in an article, as long as it has a named anchor tag in the target article. For example, your parent article might use the acronym "LDAP". Rather than defining this in the parent article, you can link the string "LDAP" in the parent article to a definition in another target Wiki article, such as a Glossary. Unfortunately, it is difficult to determine the anchor tag name in this case. You must edit the target article (where the term or acronym is defined), switch to the HTML editor, find the term, and note the anchor tag name. If there is no anchor tag, you must create one. The url to the term will be the url of the article, followed by the "#" character, followed by the anchor tag name.

For example, assume in your parent Wiki article you use the acronym "LDAP" and you want to link the first instance of this term in the article to the definition found in the article "Active Directory: Glossary". The url to this target article is:

http://social.technet.microsoft.com/wiki/contents/articles/16757.active-directory-glossary.aspx

This image shows the definition of "LDAP" in this target article:

The first step is to edit the target article by clicking the "Edit" button, as shown in this image:



Next click the "HTML" tab, as shown below:




Then click the "Find and Replace" button (the "binoculars icon") in the editor, as shown below:




Note: The "Find and Replace" button is not available in the HTML editor if you use Firefox. This is a known issue.
In this example, we search for the term "LDAP", shown below:




You may need to click the "Find" button, shown in the image above, several times to find the correct location in the article. In this example, we find this line in the HTML editor:

<p><a name="LDAP"></a><strong>LDAP</strong>

In this example, the anchor tag name is "LDAP". The complete url we need for the link will be as follows:

http://social.technet.microsoft.com/wiki/contents/articles/16757.active-directory-glossary.aspx#LDAP

Next we edit the parent article, highlight the first instance of the term "LDAP", and click the "Hyperlink Manager" button, as shown below:




In the "Hyperlink Manager" dialog we paste the url of the target article in the field labeled "URL", then append the string "#LDAP" to the end, as shown below:



After saving the parent article, test to make sure the hyperlink works as intended. In the image below the url for the link shows at the bottom when you hover over the term:

↑ Return to Top


See Also

 

↑ Return to Top


Other languages