Can SharePoint 2007 Be Used as a Help Authoring Tool?

by Tom Johnson on Feb 11, 2009
categories: blogging • technical-writing • wikis

Giovanni from Italy asks the following about SharePoint:

I am assisting a colleague with a complete overhaul of an existing Help system. It is in RoboHelp, but has legacy topics that have to be maintained in Word. The Help is for call center and business office employees regarding the proprietary, in-house computer program. We recently got SharePoint, and I would like to know your thoughts on the pros and cons of Help in SharePoint. For example, can it be context-sensitive?

To provide some more detail, we don't have any translations planned, although I suspect we will need to consider translating to Spanish at some point. There is a need to post PowerPoints and PDFs that are accessed through the current Help menu. We might have multiple authors (not sure).

We don't need any conditional text , although I think it would be useful because we have several different categories of customers. I'm also advocating strongly for context-sensitive topics. We don't need multiple outputs, not as it stands now, although I am in the process of researching content management systems and reusability, which would be a great boon to this group.

We also use Captivate and Articulate, which I would like to integrate into short show-me tutorials where appropriate.

Giovanni,

SharePoint is a good solution is if you have simple help content that doesn't need to be printed, translated, or conditionalized. In the following two sections, I've outlined SharePoint's strengths and weaknesses as they relate to help authoring.

SharePoint's Strengths

• SharePoint has Web 2.0 features, such as blogs, wikis, and RSS feeds.
• You can define granular permissions for user access based on Active Directory.
• The document library feature provides a robust repository to store and manage all kinds of help files (provided users can access the site).
• You can manage your help independent of the server your application runs on. (This allows you to make updates without going through a change release process.)
• Multiple authors can contribute content at the same time (and it's easy to do so.)
• You can customize the look and feel of the site based on CSS standards.
• With podcasting and blogging kits (additional add-ons), you can embed flash videos in posts, allow users to subscribe to comment threads, and more.
• You can add metadata ("columns") to any content, and then sort, group, or filter the content based on the metadata.
• You can arrange wiki topics in a list format based on custom-added metadata/columns. This helps avoid the confusing navigation maze that befalls so many wikis.
• You can customize search scopes so that users search only wiki content, or only blog content, or other site folders. (All scopes are available in a drop-down.)
• SharePoint has a wide community of support across the globe.
• You can integrate additional web parts (many third-party) that enhance SharePoint's functionality.
• DITA content can be manipulated in SharePoint. (See DITA Exchange.)
• Built-in site metrics allow you to see details about specific users (but the metrics tool has limitations).
• Calendar and task functionality integrate with your Outlook calendar and task list.
• You can create audience-targeted text based on groups you set up.
• The blog provides a convenient platform for release notes and other post-release information.
• You can create multiple views of the same content based on custom metadata.
• You can integrate a site-wide search for all site content (for example, online help files, wikis, blogs, Word documents).
• SharePoint allows you to continually add help topics on a daily basis without recompiling or regenerating the help system.

SharePoint's Weaknesses

SharePoint does have its weaknesses. It's somewhat of a Swiss army knife: it has an impressive breadth of capability but doesn't do any one thing particularly well. If you are planning to use SharePoint as a help authoring too, the following are SharePoint's weaknesses:

• The default blog doesn't provide a "Read More" tag nor does it allow users to subscribe to comments (unless you configure a workflow through SharePoint Designer, which unfortunately is a confusing process).
• Customizing the look and feel of the site is challenging.
• Customizing the search scopes is not straightforward.
• SharePoint doesn't allow you to export blog posts, wiki topics, or other content into a printable format.
• SharePoint doesn't enable you to apply conditional text for multiple outputs. (As a website, there are no independent outputs.) Note: You may be able to do something with the Content Query web part, but I'm not sure.
• SharePoint doesn't work as a translation management tool.
• The interface doesn't provide an expandable/collapsible tree-like navigation on the side.
• Wiki pages don't allow simultaneous edits by different users. If two users edit the same page, one user receives an error when saving the page. (However, multiple authors can, of course, edit different wiki pages simultaneously.)
• The blog can break easily if you delete the wrong field (and the only fix is to reinstall the site).
• Custom columns that you add to wiki pages are exposed in full view, but not custom columns on blog posts.
• Formatting controls are primitive. For example, continuing lists after inserting notes or images can require you to manipulate the source code.

My Overall Recommendation

Overall, SharePoint can be a good solution for help content, but it certainly has limitations. If creating a comprehensive printed manual isn't necessary, it can be an attractive format because you can take advantage of the blog and wiki formats, which do function adequately. If you have multiple authors all contributing content, or a team that needs a dynamic way to exchange information, SharePoint is a good choice.

On the other hand, if you're tasked with building several role-based guides, and you need both online help and printed manuals, SharePoint won't work for you. But remember, the printed manual is dying. You could get away with some quick reference guides instead, referring the user to the SharePoint site for more advanced questions. (You'll still always get the question, "Where can I print all this out?")

Note: You can actually create a view in SharePoint that compiles all the topics in a way that looks manual-like, and you can copy and paste it into Word without losing much formatting. But you won't have any cross-references or index, and there aren't any styles that come over that you can manipulate (just inline styles). In a sense, then, you can have a printed manual available to those who need it, but it won't be pretty and will require some clean-up each time. Still, if no one really reads the manual anyway ...

Now, about context sensitive help. I have avoided this topic because I haven't experimented much with it. It depends on the format you're using for your help (blog, wiki, page, or other content type), but pretty much everything in SharePoint has a permanent URL. The only way to integrate context-sensitive help would be to manually code your application's help buttons with the URL of the appropriate SharePoint page. This might work, but the entire site will load each time, with the full sidebar. You can't hide the sidebar and provide an lighter view of the content.

Showstoppers with SharePoint

For me, SharePoint provides three main showstoppers:

1. Lack of printed export capability. Someone always asks for a printed copy of everything, even if they don't use it. That person usually asks the project manager, who assumes or expects that the help content should be available in a manual for the user. The project manager doesn't understand the difficulties SharePoint poses with this.
2. Inability to conditionalize text for role-based guides. Sure, SharePoint allows you to create different views of the content, so you could have different online perspectives of the topics, with different table of contents. However, if the user searches for content, the search results will return all the information on the site, regardless of the view. Since users primarily search for information, this poses a problem.
3. Lack of context-sensitive help. I don't want an entire SharePoint site to load each time a help topic is called from within the user interface. That seems clunky to me.

Despite its shortcomings as a help authoring tool, the SharePoint blog works great for a team site. It provides an online platform for discussion and enables collaboration.