I'd Rather Be Writing » help authoring

Podcast: The Myth of Single Sourcing

Tom Johnson — Tue, 22 Dec 2009 05:32:20 +0000

In his controversial post, The Myth of Single Sourcing, Michael Hiatt explains:

Single-source publishing is a zombie idea that revives itself periodically and refuses to stay dead. Its zombie supporters chant its purported benefits as a “write once, publish to many” promise and ploddingly follow it as their ultimate goal for mechanized authoring and machine translation. As an object-oriented writing methodology, it is as human as present-day robot technology—good only for conveyor belt assembly or specialized tasks, and always very expensive to implement. Single-source publishing lacks purpose in today’s world of information turnover and the dynamic nature of the Web 2.0 moving to Web 3.0 landscape.

In other words, single sourcing your content across the enterprise is an idea that simply doesn’t work. I responded to the post and had a lively exchange in the comments, so I decided to interview Michael for a podcast.

In this podcast I talk with Michael about single sourcing, collaborative authoring, mashups, help authoring trends, and other topics. You can follow Michael’s blog at Mashstream.com.

(Note: We had a brief Skype issue at the start. The audio gets noticeably better at around the 5 minute mark. It’s actually a great example of the clarity that the double-ender recording technique provides instead of just using Skype to record.)

Blog Sponsors

A Few Surprises in Using a Wiki for Documentation

Tom Johnson — Thu, 29 Oct 2009 14:40:15 +0000

Recently I’ve been working on a simple calendar project that uses a wiki for documentation. Although I’ve heard a lot about using wikis for documentation, and have even used them in the past, I ran into a few surprises this time.

1. Authoring directly on a wiki screws up the history of updates.

The way wikis work, every time someone makes an edit, it’s recorded in a history for the page. When I write, I make a lot of little updates here and there, not just within one section, but across multiple sections. I can make 10 updates, apparently, in one minute (or so someone told me, who complained that I was mucking up the revision history). I like to hit Save Page often, especially if I have the whole page in edit mode (Microsoft has taught me well). When I save frequently, the version history becomes somewhat useless, as it just shows my name a million times.

Version history isn't so useful when you use the wiki as an authoring tool

Perhaps the solution is to author on a practice wiki and then transfer finished blocks of text to the production wiki when you’re ready to collaborate with others on the content?

2. The text width is longer than St. Pete beach.

I realize this is probably a setting I could control through a wiki stylesheet, but the default width of text for Mediawiki pages spans about seven or eight miles. This makes it difficult to read.

Wiki column widths are often really wide

Wikipedia has the same problem with length. The optimal width for a column of text is about 75 characters in length (less, actually).

(Here’s St. Pete beach, by the way. Next week I’m going on vacation to Florida and am definitely strolling down this long beach, which is my favorite. I’ll be thinking of Mediawiki while I walk.)

St. Pete Beach -- photo by Hanny Heim

3. Community members seem more likely to make little edits rather than create entire pages.

Last week I was at WebWorks in Texas, and I asked Anne Gentle why no one has developed a plugin to convert from wikis to a help authoring format. It makes sense that people would collaborate on a wiki, finalize the content, and then export to a more flexible format, right? Anne felt there wasn’t a business case for creating such a plugin. What?

But after working with a wiki on this project, I see what she’s saying. In my situation, members of the community aren’t going to contribute tons of content. I did receive some help from another volunteer in the beginning, and he wrote several small sections. But when I took over the page with major edits, revisions, and other additions, it kind of pushed him away.

Collaborative authoring isn’t so engaging if two people are hacking away at the same page, changing what each other writes. Authoring this way detracts from one’s sense of authorial ownership. Instead, I believe it’s more common for a single author to create the bulk of a page, and then have the community add edits, a few sentences here and there, tips and notes. The baker creates the cake; others add icing. By and large, there’s one baker per page (at least that was the case with my project).

4. Navigation is cumbersome.

Mediawiki organizes the content of each page into table of contents automatically. The table of contents can get somewhat long and cumbersome (even as simple as the content is), if you aren’t paying attention.

Writing in a wiki format forces you to think carefully about the organization of your content. If the page gets too long, you can break it up into multiple pages.

You have to think carefully about the navigation

The best-practice paradigm of topic-based authoring — authoring content in small chunks that you can manipulate and single source — doesn’t seem to apply to wikis. If you chunk each section as its own page, readers will bounce from page to page to page. It will become a dizzying experience of clicking and clicking.

Perhaps there’s a way to pull in sections from other pages, but I don’t know how to do that yet. Maybe wikis break down when it comes to single sourcing for multiple roles or audiences. Not sure here.

5. Making updates is incredibly simple.

If there’s a major strength to wikis, it’s the ease of making updates. For example, in looking over my local unit calendar help wiki as I wrote this post, I noticed a couple of inaccuracies. I nonchalantly clicked Edit next to those sections and made updates. I absolutely love the ease of updating a wiki.

For people who need to review the content, it’s easy for them to make changes, add comments, and proceed section by section. Don’t underestimate how important this aspect is in the authoring process. I’ve written before about the importance of living documentation – documentation that you update regularly based on user feedback, problems, stories, and other questions. Because a wiki is a live format, you can tap into it at any time and make changes.

On this topic, also see John Hewitt’s excellent post on living documentation and Stewart Mader’s post, Wiki: A More Productive Medium for Living Documents.

6. Wikis are a web format.

Although I wasn’t too enamored with wikis when I started this project, I’ve come to like them more and more. One aspect of wikis that draws me in is the web format. I’ve realized lately that I enjoy web design. A lot. I like working on the web. I like stylesheets and links and jquery effects and layout, navigation — everything.

I realize that authoring in a tool like Flare produces HTML output, which is a web format, but I dislike the static nature of authoring in a help authoring tool and then uploading the content to a file directory to appear in a browser. There’s a disconnect. It doesn’t feel like web authoring, even if it’s published on the web. It’s more like static HTML authoring.

Although I didn’t fallen in love with wikis in the past, the integration with the web may be enough to convert me. Part of my problem with wikis previously was my expectation that users would contribute more. When that expectation wasn’t fulfilled, I wondered why I was using a wiki.

Now I feel differently. For one thing, wikis ensure a separation of help content from application code. This means I can have access to the help even after applications are released. This is something I feel strongly about. Help content should not be packaged with the application code. When help is packaged with application code, these are the results:

little or no interaction with the user community.
uncorrectable errors that can’t be fixed.
a mindset of it’s-released-so-now-I’m-done.
no time for translation or video tutorials (because the app isn’t frozen until the week before release).

7. Wikis provide a new language to learn.

Wikis are supposed to be easy to author in, and for the most part, they are. However, they also provide a new syntax and language to learn. That can actually make authoring more fun. For example, look at this little player button in the image below.

Making an image link to a webpage

By default, in Mediawiki, images link to themselves (or to a larger picture of the image). In this case, I needed the player button to link to the video tutorial, not an image of the player button on the file:image page. You would think that making an image link to another page would be easy in wiki syntax, right? Actually, it took me 10 min. to figure this out. Here’s the syntax:

[[File:Videoplayer.jpg|link=http://lds.netdimensions.com/ldslive/nd/fresco/repository/html/luc/subscribetoacalendar.html]]

In retrospect, it seems pretty simple. But the link= part I had to dig up.

Concluding thoughts

Strangely, I started this post somewhat antagonistic against wikis, and as I’ve reflected on them, I’m now considering using wikis exclusively. I don’t know what happened, but I like the direction wikis take me. It’s the direction of the web.

By the way, if you have any feedback on how to improve my calendar help wiki, please let me know.

Blog Sponsors

User Assistance: Get your head in the cloud

Tom Johnson — Thu, 22 Jan 2009 12:15:06 +0000

User Assistance: Get your head in the cloud.

A great description of how fee-based software (SaaS) changes the priorities for help authors.

Blog Sponsors

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

Tom Johnson — Tue, 24 Jun 2008 04:59:38 +0000

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.