A Web 2.0 Documentation Idea Gone Wrong

by Tom Johnson on Feb 6, 2008
categories: technical-writing web-designwikis

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.

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?

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.

M ↓   Markdown
D
David Carrington Jr.
0 points
8 years ago

I know it's an old post, but I've only been introduced to the shit-show that is Confluence in the last year. How about: no WYSIWYG, crippled text search, no resizing table columns on the fly, and saving your work is now a part-time job. I feel like I've regressed to 1989.

Oh, and when you get edits from your reviewers...30-40 comments each helpfully designated by page number. Try explaining to your reviewers help that you actually have no idea what "page" anything is in your source file.

?
Anonymous
0 points
10 years ago

My company has used confluence for a "knowledgebase" (notes and internal documentation) for 10 years or so. We still have a (many years out of date) installation on one of our servers, and a couple of cloud instances for some newer stuff.

They used to give you access to the source markup. Our old installed version still lets you switch between source markup, rich edit, and preview tabs. They've been working on the rich text editor since we first started using, and have yet to get it right. In our old installed version, you inevitably have to go into the source to fix things when they get screwed up, or just to do thing in the first place as something are just easier that way.

However switching back and forth, it inevitable screws something up. The only safe way is to never edit with their rich text editor once you've started on editing the source.

So I assume they "fixed" their inablility to get that right, by just taking away the ability to switch back and forth. But it boggles my mind that they would do this when they clearly can't get the rich editor right either.

I always end up with pages that have weird formatting going on that is completely unfixable or inspectable in the editor. A bit of text will be indented yet no buttons get enabled when I click on it, including the outdent button, so there is no way to fix the indenting. Lines have different space between them than other again for no reason the editor will let me see or change. Some bits of text that look perfectly plain and again provoke no toolbar reaction, get rendered into icons while other identical bits of text do not. It fills me with rage.

?
Anonymous
0 points
10 years ago

Tom, it would seem that you can get excerpts to be searchable within articles...it requires another plug in though.https://ffeathers.wordpress.com/201...

Hopefully this solution works with multiexcerpt content too.

?
Anonymous
0 points
10 years ago

Thanks for the tip.

?
Anonymous
0 points
11 years ago

I have to agree with Tom - I don't like Confluence as a documentation tool much at all. I've had to work with Confluence on Demand lately, which admittedly is a really stripped down version...but so much stripped down that it is barely usable. There are so many annoying formatting issues that you can't put right because there is no access to the source code (the plug in doesn't work for On Demand) and there's no access to a css style sheet either. I have used the full product, which was better, but I'd read about the problems with content re-use, and even the use of multiple 'excerpts' requires a paid-for plug in. The amount of plug-ins needed makes it more costly than it first looks.

Given the choice, I would use Flare or Robohelp over it every time.

H
Hemal Patel
0 points
9 years ago

Looks like you have read my mind! I am working with Confluence lately. I so agree that the usage has a lot of limitation. However, I do understand the other side of the coin too. When I see the developers penning down their part of documentation, there's no other tool better than Confluence. All they need is a common platter to access, and Wiki is a way to go.

However, as a technical writer, it's tough to maintain single sourcing, conditional build tagging, exporting to PDF/Word, and to an extent the look-n-feel too.

?
Anonymous
0 points
11 years ago

I like wikis more than you do, but I wouldn't recommend mediawiki because of its fundamental antagonism to permission controls. This is a killer deficiency for most enterprise knowledge base implementations.

Confluence changed direction a couple of years ago, hiding the wiki syntax behind the WYSIWYG editor. They clearly decided to focus on the "typical business" user at the expense of their techcomm audience.

?
Anonymous
0 points
11 years ago

Yeah, Mediawiki's open permissions are problematic for a lot of situations. Mediawiki is good if your access and collaboration needs parallels that of Wikipedia, basically. Also, I'm not sure that Mediawiki's transclusion has any better results with search than Confluence. What I do like is the ability to work directly with wiki syntax or HTML. Mediawiki is also pretty robust in terms of its feature set.

Have you ever worked with a wiki that wasn't full of a bunch of outdated, authorship-unknown content?

Tom

?
Anonymous
0 points
11 years ago

Sorry, but I don't agree at all.

The argument about content re-use and comparing Confluence with DITA is like comparing apples and oranges. If you assume to use Confluence both as authoring and publishing platform, please tell me how to do that with DITA? Let your readers read XML files? How would you make sure they read only the content for the relevant audience? It is actually possible to export from Confluence and use a publishing tool chain to produce online help, PDFs, or even books (just one example that has been authored in Confluence: http://www.thelanguageofcon...)

With regards to the rich text editor in Confluence. Agreed, that it has its glitches - as many other WYSIWYG editors do too. But other than highly specialized (XML) authoring tools, Confluence lets tech writers escape their silo, and get to collaborate with the whole organization:

  • developers can provide input in same system the tech writers are working in;
  • service people can ask questions and provide feedback in the same system;
  • tech writers can include co-workers with twitter-like @-mentions and shares to ask for feedback
  • ... I could go on here, but I think the most important benefit of using a multi-purpose collaboration platform like Confluence for tech writers, is that there work becomes visible and more fun.
D
David Carrington Jr.
0 points
8 years ago

No doubt it's a good tool for collaboration: that's what it was designed for. But as a doc creation tool it is simply terrible.

?
Anonymous
0 points
11 years ago

Stefan, thanks for your comment.

DITA does separate authoring from publishing. In some ways this is problematic because it lengthens the publishing cycle. When you want to update a page in your help, you have to regenerate all the help and re-upload it to your server. With wikis, you just edit the page, make the change, and when you save the page, the browser publishes it.

Additionally, DITA's paradigm is to publish different variants of the content as separate deliverables. However, having output 1, 2, and 3 may not make sense for audiences who are not that divided and who want to see content for outputs 1, 2, and 3. Dynamic content filtering, which would allow users to select attributes and have the content dynamically shape around that attribute on the same platform, is something only possible with advanced DITA publishing platforms.

I'm not really sure what you're asking when you say, "If you assume to use Confluence both as authoring and publishing platform, please tell me how to do that with DITA." I'm not suggesting that you do that with DITA. XML doesn't automatically render into HTML in the browser. (There is a guy who created that functionality to some extent, but it's a work in progress.) I'm arguing that this paradigm in Confluence is what gives rise to the complications I described.

Re "It is actually possible to export from Confluence and use a publishing tool chain to produce online help, PDFs, or even books," yes, I am aware of this. The PDF looks pretty good, I have to say. However, PDFs aren't a deliverable I need. The HTML is pretty weak -- it's a single file with jump links. I think Microsoft Word can also publish out to HTML, but that doesn't mean I'd use it to publish a website.

Re books, such as with the Language of Content Strategy, that's an area I don't know much about. It would be neat to learn more about the back-end publishing workflow of how you're mapping Confluence pages to an HTML site page. Even so, it seems kind of like an inflexible model. What if I change around pages and IDs -- I assume that I would have to adjust all the mappings. If you want to write a guest post that describes how The Language of Content Strategy site model works from a technical level, I would welcome it.

As far as the collaborative benefits to wikis as an advantage that outweighs the lack of wiki markup, I admit that in some environments, collaboration on wikis can make tech authoring more fun. But wikis are problematic overall. They lead to redundant, outdated content (ROT). I explained why here.

?
Anonymous
0 points
11 years ago

Thanks for the feedback and thanks for the offer to write a guest post on the making of "The Language of Content Strategy". I'll get back to you about it.

Just on additional note on redundant, outdated content: IMO this is not a problem of a particular technology, it is an organizational problem: If there is no ownership defined for content, and the content is left to who ever wants to edit it, then you will get outdated content. - It doesn't make a difference, if it is a wiki page or a DITA XML file.

Only, it will easier for co-workers to provide feedback and fixes, if the content is a wiki page instead of a DITA XML file.

?
Anonymous
0 points
11 years ago

>But you can’t automate the variant based on login permissions.

Yes and No. If you use Bob Swift's plugins , you can do some fancy variable content based on the individual user.

?
Anonymous
0 points
11 years ago

Good tip, Ellis. Which plugin from Bob Swift are you referring to? I see he has about a dozen of them.