I’d Rather Be Writing - Tom Johnson

I sometimes feel that my life online varies drastically from my life at work. Online, I blog and publish podcasts and write about wikis and Web 2.0. But at work, I used Flare, InDesign, Word, and other tools to create standard help deliverables, such as the User Guide, the Quick Reference Guide, and the Video Tutorial.

For a long time, I’ve wanted to take my documentation into web 2.0 territory and enable user interaction and feedback, but I’ve been hampered by tools. Around some people, just saying the word “tool” brings up immediate negative responses. For example, when I interviewed Scott Abel about social networks and asked him about Ning, he didn’t want to discuss Ning because for him — and many others — tools are merely a selection of wrenches in a hardware store aisle. You figure out what you need first, and then you pick your tool.

I don’t think anyone who is eager to implement web 2.0 interactivity into their documentation can be so indifferent with tools. This is because there are no good web 2.0 tools for documentation. Right now everything’s a hack. You have to cobble together a solution from various things and try to make it work.

The question of tools plays an even larger part for writers who are subject to IT policies about what they can and can’t install. Even if you have free reign to use whatever authoring tool you want on your computer, many web 2.0 tools are database driven and require server components. Many infrastructure departments are particular about what you can and can’t install on their servers, assuming they give you space to install anything at all.

Last month I was dealing with these tool obstacles when a guy at a WordPress blogger dinner suggested that I work with the tools and platforms already endorsed by my company. Seems obvious, I know, but when you’re a WordPress devotee, considering any other tool for blogging seems blasphemous.

At my organization, the closest Web 2.0 tool we have is SharePoint 2007, or MOSS 2007, to be more accurate. Although SharePoint has a bad rap, the latest version is actually quite innovative, and includes blog, wiki, and RSS functionality. That said, the complexity of SharePoint’s code makes it a hard beast to tame.

I’m still in the process of testing my prototype, but I’ve learned a few things about SharePoint that may be useful to others.

With SharePoint, Blogs Make More Sense Than Wikis

The blog and wiki features in SharePoint are extremely close cousins. The source code for both a wiki page and a blog post function the same, so you can easily move your content from one format to another by copying the source code of a wiki page into the source code of a blog post. The source code consists of a lot of DIV tags referencing external styles with unrecognizable classes. And everything is unavoidably structured with inline styles.

SharePoint wikis and blogs do have some differences:

• The wiki automatically keeps revision history and shows incoming links.
• Any columns you add to your wiki appear exposed to the reader’s view.
• Wikis lack a master wiki template that you can modify to change all wiki pages.
• The blog displays the writer’s name and timestamp below the post and offers a permalink.
• The blog allows you to aggregate the posts in categories, and then see the latest posts in that category.
• The blog provides a comment field below the post, and includes a view that shows all comments.
• The blog allows you to attach a workflow to the comments field.
• Wiki pages are individual aspx pages, whereas blog posts are contained in a database somewhere.

For both blogs and wikis, the Edit button appears based on the user’s permissions for the site. In general, the blog feature is more robust than the wiki.

The Main Reason to Use the SharePoint Blog Rather Than Wiki

The main reason you might consider using SharePoint’s blog rather than wiki is for the comments feature with the blog. SharePoint’s wikis are simple to use, but they lack any kind of discussion ability. This can make collaboration intimidating. Users have to be bold enough to go behind the scenes and totally change the author’s original text.

Few actually do that. In my experience with wikis in documentation, only about 0.1% of the 3% of users who read the documentation make any edits, and the edits are either slight (such as correcting a typo) or the edit makes the documentation worse.

The comment form provides the equivalent of a discussion page for your wiki. Users are much more inclined to leave a comment.

Try as you might, it’s not possible to add the blog’s comment form below your wiki page. (A few people led me on a wild goosechase about an “Append Comments” column, but that only exists with the Issue Tracker, and it’s quirky. Actually, the blog comments feature is quirky too — just start reloading your page in Firefox when you have text in your comment form.) Some wiki “kits” that enable comments below pages are being developed, but aren’t yet released.

No Table of Contents Pane

As I was configuring my SharePoint site late one night, it dawned on me that SharePoint (and any other wiki platform) lacks the table of contents pane on the left that is so common to webhelp formats. The ability to navigate the table of contents on the left and see topics in the main content window seems critical for navigating a help system.

When I realized this, I almost stopped my entire SharePoint endeavor. But by the next morning, I started remembering the need for a communication venue and the importance of getting user feedback, so I opened SharePoint again and soon discovered something wonderful. Although users have to click the Back button to return to the table of contents, the blog feature allows you to categorize your posts (help topics) with category labels.

When you click the category, it shows you, in reverse chronological form, all the posts for that category. If you set the publish dates to the order you want, it provides a nice chapter-like feel to the online help. Readers can scan down all your help topics in a particular category. That doesn’t exist in any webhelp format I’ve seen, and for me, it’s preferable to have this larger view of all topics in the category.

Additionally, you can create mini-TOCs for each category by adding a view that shows only the post titles. Nice. It seems that for every drawback with SharePoint, there is an advantage that compensates.

Single Sourcing Printed Content

One of my biggest concerns is single sourcing the material. I pretty much settled on the fact that I’d have to do some copying and pasting and reformatting for 1-2 days to generate the long printed manual that someone would inevitably ask for. SharePoint’s blog content can’t be exported to XML or easily removed, as far as I know.

However, there may be a workaround to the single sourcing problem. Although you can’t export from a SharePoint blog to Word, you can use Word 2007 to compose your blog posts, and then publish to a Word blog. Thus, if you author your content in Word, you can then single source it to your blog. This especially works well for maintaining two image sizes.

Unfortunately, I think this method would require you to copy and paste the topic into a new Word document that you wanted to post to your blog. I haven’t explored this much yet.

You can also create a view that shows all your blog posts in one long display (not just the latest 10). If you sort it right, prioritizing the right columns, you can get it to look just like a manual. Then you can copy and paste it to Word, apply some H1 and H2 hierarchy to the headings, add cross-references, and be done soon enough.

I’m not too worried about the long printed manual because, as far as I can tell, no one has ever appreciated it when I handed him or her a 200 page manual. Invariably, anything over 50 pages gives someone a heart attack. The long manual is dead. Most users want a short guide followed by a comprehensive online resource they can search. So I’m planning to most likely maintain a 5-10 page printable guide in InDesign or Word that isn’t single sourced.

Single Sourcing Online Content

The single sourcing of online content is where SharePoint really excels. SharePoint allows you to add metadata fields to each post (these fields are called “columns”). You can then create views based on the columns — views that include pages that have certain columns, views that sort by certain columns, views that only contain pages that have certain selections in certain columns, and so on. I’ve added columns that identify different roles, and then I create the views based on those roles. It’s quite simple and powerful.

Site Metrics Advantages

SharePoint offers some other advantages that are pretty compelling. It allows you to see how many times the help site has been accessed, what topics have been viewed, the keywords users have entered in searches, and who the actual users are. This kind of knowledge is reason enough to look more seriously at SharePoint.

An Analogy of Where I’m At

Well, that’s where I’m at. It’s not the prettiest Web 2.0 documentation solution, but it’s a start. The situation reminds me of a spoon I once saw that had been sanded into a knife by an escaped prisoner. Apparently the prisoner needed a weapon, and the only thing available was a spoon, so he tried to make do with it by sanding the heck out of the sides to make it triangular.

In the end, I assume the spoon didn’t work because the police found it lying on the ground, and the prisoner was eventually caught. But it was a great attempt, and it demonstrated the resilience to improvise and adapt based on what’s currently at your disposal.

It’s an Alive Web-like Organism

Finally, I like the idea of SharePoint as a documentation tool because it’s a medium that’s alive. Most other help authoring tools are static. The Internet might as well not have been invented — it makes no difference. To me, that is the saddest thing about the tech comm. authoring tools. You author in a program on your own computer, and then upload to a file directory somewhere, and then leave the content as is until you update it again. Sorry, but that misses out on everything cool and dynamic and web 2.0 that has happened in the last 10 years.

With SharePoint, your documentation is a living entity, an organism that is constantly growing and breathing online. Like my blog — I receive comments. I look at hits. I can watch visitors in real-time. I publish comments back to it. Readership subscription grows and shrinks (but mostly grows). I see incoming links come back to it, and I link to other sites and people. As insights come to me, I add them to the blog, and other readers come and see and leave comments, and I respond. It is a living, growing, breathing body of information. Help should be the same way, not a static file that gets a push update once every 6 months.

RSS Subscribe

Related Posts

• My Compromise with SharePoint — What Works and What Doesn’t
• Top 10 Workspace Configurations for Technical Writers
• SharePoint Wikis: Both Liberating and Frustrating
• Video on SharePoint 2007 Wiki, Blog, and RSS Functionality from Microsoft’s Channel 9
• Usability Newsletter Interview – “I’d Rather Be Writing – The Man Behind the Words”

Tags: metrics, moss 2007, Ning, Scott Abel

Comments

You can leave a response, or trackback from your own site.