My Compromise with SharePoint — What Works and What Doesn’t

In a previous post, I mentioned my desire to use SharePoint as a help authoring platform because it provides a Web 2.0 experience that is company-sanctioned. SharePoint not only has blogs, wikis, and RSS feeds, but also integrates with Active Directory, Outlook 2007, and has integrated search across all content.

However, the more I tried to use SharePoint as a help authoring tool, the more problems I ran into. SharePoint doesn’t handle role-based content very well. For example, if you have administrators and regular users, it’s not easy to create two versions of the same help material. SharePoint does have audience targeting, but only if your audience is already tagged with roles in Active Directory (and if active directory is integrated with SharePoint).

Additionally, SharePoint doesn’t single source well. For example, if you have to create several role-based guides, you’re in for a challenge. You can create views in SharePoint where all content shows, and then copy that content into Word. But then you have to reformat much of it, add cross-references, index entries, a table of contents, headers and footers, sub-lists, and other formatting.

Formatting the content in SharePoint itself is also a kluge. SharePoint’s wikis are primitive. They don’t allow comments. And if you add metadata to sort the wiki pages into different views, the metadata (columns) appear to the user.

SharePoint’s blog posts give you a comments field below the post, but it still looks too blog-like. You lose out on the table of contents navigation pane on the left. You can’t quickly navigate through an outline of content. However you try arranging the help topics, it just doesn’t look like help. Users are a bit perplexed and don’t immediately know how to use the system.

Even more important, though, almost no one comments on help topics. As much as I’d like to web-2.0-ize my help, it’s not the same as a personal blog on the web. People at companies simply aren’t inclined to comment on help, so going out of my way to add commenting features below each topic is like adding engravings in sidewalk cracks — sure it may look nice, but no one has a use for it or cares much.

I didn’t renounce SharePoint altogether. I’m still using the web space to organize my content and the blog to communicate information to users. So I’ve made a compromise. First, I customized the SharePoint site to look like a sharp looking website rather than a SharePoint site. The default help URL in my application takes users to a SharePoint landing page, where they can choose their help deliverable — online help, quick reference guide, user manual, or video. All my help content is hosted on SharePoint, so I can publish and update it whenever I need to.

“Blog” is a button at the top of the landing page. On the blog I post release notes, answers to common questions, and other tidbits of information, like the application’s release cycle and upcoming training. I must admit, though, that I don’t have as much to say on my product blog as I originally thought.

Finally, I’m still tracking visitors to the help. Because of the integration with Active Directory, I can see the names and departments of everyone who visits the help. And they can subscribe to RSS feeds and email alerts for the blog. (Now if I can just teach them how to pull RSS feeds into Outlook 2007 … )

I’m not saying SharePoint can’t be used as a help authoring tool, but it’s more suited to knowledge base situations, where you have hundreds of topics and you’re not expected to format them out into any printable guides.

And I’m also not discounting the value of Web 2.0. In some situations, such as promoting an application on the web, more interactive help topics in the form of blogs or wikis might be powerful. But inside the firewall, people often just want to do their jobs.

I returned to Flare for my core help authoring tasks. Let me just say that in doing so, I felt a sigh of relief. Flare provides the feature set for help authoring that I need — conditional tagging, multiple outputs, modifiable skins, hotspots, advanced styles, etc. Despite its quirks, it works.

The way I see it, I’m taking the best of both worlds and combining them.


Madcap FlareAdobe Robohelp

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • Pingback: Gryphon Mountain Journals()

  • AutoSponge

    “SharePoint does have audience targeting, but only if your audience is already tagged with roles in Active Directory (and if active directory is integrated with SharePoint)”

    You can also use SharePoint groups for audience targeting. You just have to remember to build the group in SSP. Also, it sounds like you haven’t tapped into Search yet.

    Take a look at creating Search Scopes, the tag cloud codeplex project, best bets and key words, customizing the Search Core Results Web Part, and authoritative pages. All of those can help with “help.”

  • Pingback: 06/24/2008 Writing Jobs and Links : Writer’s Resource Center()

  • Pingback: Get the Latest SharePoint News - SharePoint News()

  • Pingback: footers in word()

  • Gina Fevrier

    I’m a tech writer at a software company and have just been tasked with reorganizing our SharePoint (WSS 3.0) site. What’s the best way to create help topics and post them on SharePoint? I’ve seen Microsoft’s articles on customizing the online help, but there’s a lot of programming and I’m not a developer, and ours don’t have time to help. Currently one of the developers posted some help topics as a List of tasks (?). Really weird to me. I’ve read in your posts that a SharePoint blog is better than a WIKI. I’m really going about this blindly because I don’t have access to the administrative functions of our SharePoint. Thinking about downloading a trial and using it locally. Any ideas?

    By the way, I am so glad I found your blog today — it has a ton of relevant information.

  • Tom

    There’s not too much difference between SharePoint’s blog and wiki formats — it all depends on how you edit the permissions. Blog posts allow comments below them; wikis don’t. Wikis show all the metadata columns; blogs don’t.

    In the end, both formats are problematic because you can’t single source or export the content into another format — they’re trapped in SharePoint. That was a big enough deal for me to abandon the platform (except as a landing page).

    If you don’t have access to admin functions or to SharePoint Designer, you won’t be able to do much at all. You might download a “trial” perhaps if you have a virtual server and know how to set that up. The best trial is to experiment on a test site already set up on your company’s server.

    Rather than a blog or wiki, you might want a different site altogether. There’s one called a knowledge base or something — I think that might work best.

  • Gina Fevrier

    I just need a blog or WIKI on SharePoint for help topics regarding our internal SharePoint site. I use RoboHelp 7 for our customer help docs. I don’t want to use RoboHelp because I want our own development team to contribute to the SharePoint help topics without having to use RoboHelp (since I’m the only one who uses it). Thanks for the advice — this is really a good site.

  • Tom

    If you want developers to contribute, use the wiki. But be warned that getting people to contribute substantially to a wiki’s help documentation is next to impossible.

  • Sravan Kasyap

    A nice article which makes things clearer. But i was wondering how would Flare store the topics and other details in the database. Also was wondering how easy it is for a developer to perform the context sensitive help. What i mean is If i have a webpart in the shareppoint and i have to tie the context sensitive help to that field in the webpart, is it possible? For example, if i have username and password fields in the webpart, if i select username field and press F1, i expect to show a certain page in help which reflects the username topic. Is it possible with Flare? How great are the API’s with in the Flare. Can i do a search on a key word and automatically populate all the available topics pertaining to that search? Finally how do we publish the help topics to Sharepoint?

    I am asking these questions to you as you have already used the product. Well i have sent a mail to the MadCap Flare company for more technical support for which i did not get response yet.

    So, I will really appreciate if you could take out your couple of minutes to answer my questions.

    Thanks in advance. Please mail all your communicaiton to

  • Your r an idiot

    you r an idiot from your article I could see that you must be exposed to sharepoint for a month or two. First, learn things before you can apply it.

    • Tom

      When I think of designing a SharePoint site, I’d rather hit myself in the face with a brick.