A Web 2.0 Documentation Idea Gone Wrong

Many of us want to integrate innovative Web 2.0 practices into our online help. But if we create blogs, wikis, or other interactive features outside the help file, users may never use them.

I’ve been using SharePoint 2007 as a file repository for my online help mainly because of the publishing control it gives me. And since I was already using SharePoint as my file repository, I thought I could also take advantage of another feature — SharePoint’s blog/forum — to address another problem technical writers face: post-release questions.

SharePoint Site

After an application launches, if you hang around presentation sessions, user groups, and support centers, you realize that users ask a lot of questions not addressed in the help. It’s not so much that the help has holes, but that users come from so many different business backgrounds and all want to use the application in their own way, according to their own style of working.

When I began to see these questions arise, I carefully noted them and decided to answer them using the blog/forum feature in SharePoint. Because my help files were posted on the same platform, searches made on the SharePoint site returned results from both the online help and the blog — a seamless integration, I thought, between the static online help file and the dynamic wikis and blogs of the Web 2.0 world.

I made a clear link to the “User Forum” on my help’s home page, assuming that users who didn’t find answers in the help would click the user forum and try there.

Then, during a user research session, where I asked a novice user to perform a list of difficult tasks (forcing him into the help), I realized a major flaw in my thinking: The user never went into the user forum. The user never searched from the SharePoint site. The user never knew the forum even existed!

The way he used the help file was very precise. He had a question, he navigated to the topic in the TOC, he expanded the hotspots, he scanned for relevant information about his question. If he didn’t find it navigating the TOC, he did a quick search (typing the action he wanted to perform, such as “add mailbox items”).

When he still didn’t find it, he shrugged his shoulders, returned to the application, and started experimenting with different buttons and options, trying to solve the puzzle somewhat like trying to solve a Rubik’s cube.

[youtube tSqUcrFJ498]

I learned that if the help material isn’t in the online help file, it doesn’t exist. So what if you have a separate user wiki, or a product blog, or a user forum. If it’s not intimately integrated into your online help — in fact, if it’s not included in the right book on the right topic in the help, where all other information about that topic is grouped — you might as well delete it. Don’t even bother with it. Users assume all relevant help information is in the help file, and not somewhere else.

Kathy SierraKathy Sierra, a prominent blogger who suffered an unfortunate online demise, wrote an influential post called “The best user manuals EVER.” In it, she explains why some horse-riding guides from Parelli are so powerful:

the guides group the problems you might hit in a particular task right there with the instruction for that task. Forcing a user to go to a separate “Troubleshooting” section of FAQ list is just…wrong. That doesn’t mean you shouldn’t have those separate sections, but you should duplicate pitfalls and problems and include them in just-in-time job aids (physical or online).

Context-sensitive FAQs–done right–can make a dramatic difference in software, and greatly reduce the user’s cognitive load.

In other words, just as help needs to be context-sensitive in applications, information should also be context-sensitive in the help. If the user is trying to learn about proper saddle mounts, all relevant information should be found in the chapter on saddle mounting. You shouldn’t have some saddle-mounting info in a troubleshooting section, some in a user forum post, some in a blog screencast, some in a quick reference card whose link you posted on a SharePoint site.

Exceptions exist, particularly in larger applications that have thriving forums where hundreds of users regularly exchange information. But for smaller apps, or for company apps where the idea of a user forum may be new, by and large users don’t jump from site to site, searching different databases. There is one search, one help file, one location for the answers.

Despite my failure to integrate web 2.0 into my online help, I don’t regret using SharePoint as my file repository. By hosting my files in a document library on SharePoint (rather than including them with the application code), I can update my files anytime I want. If a user asks a question, I can add it to the online help and then republish the help the same day, without waiting for the next production code release.

And this is just what I’ve decided to do: drop the forum (and thereby eliminate the hassle of updating scores of forum posts with each new version), and instead include relevant forum information in the online help folder where it belongs.

Unanswered Questions

What about Madcap’s Feedback Server? Doesn’t it solve the problem of having a separate user forum from the online help?

At first glance, it would appear so. However, the Feedback Server is too new to gauge its effectiveness. Right now, the Madcap user forum is where I post my questions and look for answers, not the comments in a help topic. But maybe things will change. One day I plan to take everything I learned from the user forum and append it directly to the appropriate topics in Flare’s online help.

So are you dismissing wikis as viable ancillary tools for online help, in contrast to what Anne Gentle was half-way considering?

Sort of. I’m raising concerns about help material that isn’t unified in one location. I’m saying most users usually look in one place only. Additionally, updating hundreds of user forum topics can be incredibly time consuming, and links in forums also lock you into keeping your specific help file structure/names from version to version. Help is more useful if all topics (including user forum nuggets, knowledge base articles, or support call logs) are grouped by topic in the online help.

What is the best way to deal with post-launch information (i.e., questions not addressed in the help after the app. launches)?

Make sure you have publishing control over your help, and then on a weekly basis (or so), take the questions you’ve received and use them to strengthen your help file. You may find you need to add a “Troubleshooting X” topic where you answer, perhaps with expanding hotspots, a miscellaneous hodgepodge of questions.

Is there a place for ancillary material outside the help?

No. If it’s relevant material (e.g., PowerPoint presentations, user guides, quick reference cards, Visio diagrams, screencasts, and so on), they should be included in the relevant places in the online help file. Sure they can exist on their own resources page, but if you’re not centralizing information about the topics, most users won’t find them (unless you’re sending users the material as a welcome package or something).

When I host my files on SharePoint, users are prompted to authenticate. I can’t have that.

If you face authentication issues with your SharePoint site, set up your SharePoint site with anonymous access by going to Site Actions > Site Settings > Advanced Permissions > Settings > Anonymous Access. Users won’t be prompted for their passwords.

Do you enjoy asking yourself questions, as if someone else had asked you?

Yes, I find the format very enjoyable. Any more questions?

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.

  • http://sharepoint.microsoft.com/blogs/LLiu Lawrence Liu

    Thanks for describing your real world scenario! We can always use more of these to help us improve future versions of SharePoint. It’s obvious that there would be much greater value to the user (through easier discoverability) if the wiki, discussion, and other supplementary info about a piece of content were seamlessly integrated into the default view of the content. In the wiki case, a good example would be the SharePoint SDK on MSDN: http://msdn2.microsoft.com/en-us/library/ms550992.aspx. In the discussion case, there would be a “Discuss” link for each wiki page similar to what’s provided by the Community Kit for SharePoint: Enhanced Wiki Edition. Thoughts?

    Lawrence Liu
    Worldwide Community Lead
    Microsoft SharePoint Products and Technologies

  • http://idratherbewriting.com Tom

    Lawrence, thanks for your reply and attention. You certainly have your finger on the pulse of the web. How do you manage to stay so blog-aware?

    I like the discussion section at the bottom of the wiki that you showed me. Nice. Is that in beta, or can I implement that on my MOSS 2007 site right now?

    You asked for ways to improve future versions of SharePoint. Here are what I’d like to see:

    1. A “Read More” tab for blog posts.
    2. A “Subscribe to Comments” check box for blog posts.
    3. Ability to add a blog web part to a team site (rather than creating a separate blog site)
    4. Removal of the default Quick Launch layout that organizes content by format rather than topic (this is why so many SharePoint sites have scattered navigation)
    5. A location where I can go to ask questions and get answers about SharePoint (maybe you can recommend one)
    6. More intuitive setup with the idea of columns (I get it now, but it took me a while)
    7. Removal of kerberos authentication for feeds (I just want the feeds to work; it’s crazy that they don’t work in a secure network without some kind of technical kerberos tweak)
    8. Better feedreader that allows you to aggregate and sort by post date (does Microsoft have a feedreader? I don’t even know)
    9. Integration of TechSmith’s Jing (Microsoft should just buy this product because it would be immensely useful for all the project teams)
    10. RSS feed icons on every page (rather than tucked away under the actions menu)
    11. Simultaneous editing ability with the wiki (if two people edit at the same time, only one gets to save the edits)

    Things I really like about SharePoint: blog, wiki, top tabs, control over the Quick Launch, comprehensive search, one-click publishing, meeting spaces, graphics, interface, usability. MOSS 2007 is light years ahead of its predecessor. Microsoft is really on the right track.

  • Pingback: Core Dump()

  • http://heidilhansen.blogspot.com Heidi Hansen

    This post reminds me of the Office Help experience: you use the Help menu to open a Help search box and type your search, and then it searches different repositories. The default repository is Office Online Help (both Assistance and Training), which returns articles, Web pages, Training, and Help topics. To conduct a narrower search, you can search using Office Offline Help. To search other repositories, you can search the Clip Art and Media repository, the Office Marketplace repository, or the Research repository.
    Perhaps your Web 2.0 experiment didn’t *fail* so much as it just exposed that one Search box is needed to query numerous repositories at once, with the added bonus of search results that have icons and mouse-over text that tell you which type of resource it is, and also additional options to narrow the search to one repository as desired.
    Sifting through the comments to enhance the Help is an excellent practice. However, have you ever noticed that Troubleshooting topics often duplicate the same information that already exists in procedural topics? It seems that tips and notes in existing topics are often a better way to handle user problems (unless you have a one-stop-shop for Troubleshooting that users really like and turn to); the real key, though, is probably to figure out what they searched for and why the topics that were returned did not answer their question.

  • Pingback:   Web 2.0 and documentation don't always play well together by Communications from DMN()

  • http://www.justwriteclick.com Anne Gentle

    Tom, what a great experiment! Thanks for writing it up for us all to learn from. We’re not always able to try out these Web 2.0 experiments ourselves so it’s fortunate you are sharing your findings.

    My favorite line is “information should also be context-sensitive in the help.” I think Heidi has nailed the issue with her observation of the need for searches through different repositories. It’s not always easy for us to hook it all up, though, but making sure the search works through all supplemental information would go a long ways in helping the user troubleshoot the application.

  • Pingback: Finding and following conversations - applicable for technical writers? « just write click()

  • Pingback: Beginners Guide – Secure Network | ASIDO JAYA()

  • Pingback: It’s Not Your Product, Your Documentation Just Sucks | MindTouch, Inc Blog()

  • Pingback: It’s Not Your Product, Your Documentation Just Sucks()