In part 1, we looked at some basic concepts and structure of SharePoint help collections.
In part 2, we looked at the internal structure of a help collection, and what is required to create and modify one, from high level.
In this post, we will look at some advanced topic, include:
-> context sensitive help
-> help maps
-> related help topics (those “see also” links)
BlackCompass offers a free help collection builder, to help you create, modify and deploy help collection. Get your free copy now , there are also full tutorials available.
Help context and help maps
Help collection can be context sensitive. A help context is similar to help category, they differ by the fact that, help category is a visual. Like this help category:
Multiple help topics (those links on the page) belongs to this category.
Help context is different, it is not visual. Consider this example, this url: http://senmossdev/sites/NonPublishing/_layouts/help.aspx?lcid=1033&key=antivirus will bring up this page:
What you are seeing here is actually help topic MS.WSS.ADMIN.HA10030863 (under the MS.WSS.ADMIN). What happened here is a key word (antivirus) has been associated with a help context, and help context points to this help item (MS.WSS.ADMIN.HA10030863). To accomplish this, you need a help map.
Help maps
Help maps associate key words to help context. Help maps are xml files located here <12hive>\TEMPLATE\XML\HELP
Let’s open one up and see what’s inside
As you can see, the structure is simple, for each <helpmap> node, you need to specify the key word, the help collection id, and the context Id.
The final step is to link the help context to a help page (help topic), this is specified in the help collection manifest xml. The help collection example here is MS.WSS.ADMIN.manifest, let’s open it under the <12hive>\HCCab\1033 (or other locale) folder.
In this section of the manifest, help context MS.WSS.ADMIN.antivirus is the ”relatedItemsPointingToMe” for help item MS.WSS.ADMIN.HA10030863.
So in summary, help maps link keywords to a help context, and the manifest of that help collection links this help context to a help topic.
Related help topics (those see also links)
On any help topic, you have a “See Also” section down the bottom, containing other links related to the current topic.
Lets you are on help topic A, and on this page (A), in the “See Also” section, you will a link to page B. In this case, in the manifest xml, under help item B, you will see A “pointing to it”. Consider this example:
Open up the manifest xml for help collection MS.WSS which is (MS.WSS.Manifest.xml)
As you can see, item MS.WSS.HA01161002 points to item MS.WSS.HA01161052. So on page MS.WSS.HA01161002, there should be a link to MS.WSS.HA01161052, lets confirm this. Open item MS.WSS.HA01161002 using this url: http://senmossdev/_layouts/help.aspx?lcid=1033&tid=MS.WSS.HA01161002 you will see this page:
Note the link “PV function” links to url: http://senmossdev/_layouts/help.aspx?lcid=1033&cid0=MS%2EWSS%2Emanifest&tid=MS%2EWSS%2EHA01161052
This is the end of the series on SharePoint help collection building. As mentioned, BlackCompass offers a free help collection builder, to help you to manage this process, go ahead and it out. There are also full tutorials available on BlackCompass website, showing you how to build a help collection from ground up.
If you feel there is some more unanswered questions, please leave a generous comment or email me direct Sen.Wu@blackcompass.net
Great articles. I am currently diving into writing help for SharePoint 2010. I have used the Blackcompass tool and found it works great.
My open question is what would you recommend as the best tool for actually authoring the content? Something that could be used for initial creation of content and on-going maintenance. Microsoft Word seems inadequate from an image URL perspective it really only does well with absolute URLs which is not something we would want. And I’m looking into Adobe Framemaker but that might be overkill.
As for images, it seems you can embed them as described in these articles or add them to the _layouts directory and they would be accessible which may be nice if you are using the same image multiple times. The main concern/question is what is best for a previewing and actual content authoring perspective.
Any thoughts would be appreciated?
Hi Deborah,
These help pages are just staic HTML pages, I can share a few thoughts:
1. Keep them simple, just static text and images if you can, dynamic scripting like javascript may complicate things
2. You don’t have to put images in the _layouts directory, you can actually put them in any document library which users have access. To build a proper help collection, embed the images in the acutal help collection, as an help item, refer to the tutorials provided on the blackcompass website
3. I noticed SharePoint developers tend to use SharePoint designer (free download) to author pages, you need html/css skills, for a more advanced tool, maybe visual studio?
It is (barely) possible to create SharePoint custom site Help collection using a Microsoft Word document as the source, processing it using RoboHelp, then using DreamWeaver to fine tune the files. Not for the faint of heart, though.