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.

In this podcast, I talk with Scott Abel about social networking, in particular The Content Wrangler community he started at TheContentWrangler.ning.com. Scott talks about this new social network specifically for technical communicators. But he also explains the value of social networks for your help deliverables. Social networks can help users connect with one another and also help technical communicators better understand their users.

Podcast Topics

Topics in this podcast include:

• Reasons why Scott started The Content Wrangler social network community
• What social networking is and how it contrasts with listservs, blogs, and podcasts
• One advantage of social networks — you can create subgroups based on more granular niches
• What to do after joining a social network
• The importance of member photos in social network interaction
• Why social networking is not limited to MySpace and music videos
• The ability for members to create blogs, post events, and do other innovative things
• How the social network allows users to connect with other users, connect with jobs, and connect with events
• General guidelines for using the social network: experiment and explore, you can’t break it
• Problems people encounter after joining the social network
• The preoccupation with tools that technical writers have, and why “Ning” itself is irrelevant
• Criticisms and questions Scott has received about the social network he created
• How content is featured on the main page
• What it means to be a group leader/moderator and participant
• The mistake some technical writers make in thinking they can be Miss Cleo
• What Scott has learned about his community of users, and how it influenced the content he publishes
• The global community of technical communicators that is part of The Content Wrangler social network

Resources

• Check out The Content Wrangler social network
• View Scott Abel’s blog
• Learn more about Ning
• Check out the podcast’s intro music, Velveture by Ocean Alexander
• Visit my page on The Content Wrangler social network (and feel free to add me as a friend)
• Join the Podcasting Group on the social network
• Join the Blogging Group on the social network
• Become a member of the Content Wrangler community

Contacts

To contact Scott, send an email to scottabel@mac.com. To contact me, send me an email at tomjohnson1492@gmail.com. I love to hear from listeners, so if you have feedback about the podcast, let us know.

I find it touching that someone would think of me while reading the article. Actually, I read a sneak peak of the article in yesterday’s Blog Herald. It made me think hard about how much I’ve been posting lately.

Here are a few excerpts from the article:

Two weeks ago in North Lauderdale, Fla., funeral services were held for Russell Shaw, a prolific blogger on technology subjects who died at 60 of a heart attack. In December, another tech blogger, Marc Orchant, died at 50 of a massive coronary. A third, Om Malik, 41, survived a heart attack in December.

Other bloggers complain of weight loss or gain, sleep disorders, exhaustion and other maladies born of the nonstop strain of producing for a news and information cycle that is as always-on as the Internet.

…

“I haven’t died yet,” said Michael Arrington, the founder and co-editor of TechCrunch, a popular technology blog. The site has brought in millions in advertising revenue, but there has been a hefty cost. Mr. Arrington says he has gained 30 pounds in the last three years, developed a severe sleeping disorder and turned his home into an office for him and four employees. “At some point, I’ll have a nervous breakdown and be admitted to the hospital, or something else will happen.”

“This is not sustainable,” he said.

The article exposes the negative physical effects of blogging not often mentioned — sleep disorders, weight loss/gain, nervous breakdown, and heart disease. In the addictive drive to write more and more posts, the blogger often embraces an unhealthy physical lifestyle.

My Response

If I didn’t have blogging and podcasting as my hobbies, I would probably lead a more active lifestyle, would go to sleep earlier, and might be more productive in all my other endeavors.

Anytime that any hobby, be it blogging or basketball, begins to hinder your health, stop posting/playing so much. Unless you’re making a living from it, no hobby should detract from your mental/social/physical health.

On the other hand, blogging and podcasting energizes me and makes me enthusiastic about life and my career. Since my wife also blogs, our blogs have given us a lot to talk about.

Blogging gives me a sounding board and a space to publish my thoughts. The rewards of blogging are numerous — interacting with others, engaging in exchanges about the latest trends, thinking analytically about the day’s events. It makes life a lot more engaging.

Most of all, blogging gives me a space to write and allows me to express the creative side of me that is often left dormant during the day with technical writing.

A Solution?

How can one put aside the negative effects of blogging? I’m not a model example of what I’ll recommend, but here are 5 tips I’m trying to implement:

1. Do the most important things first. Whatever your priorities are, make sure you do them before you begin blogging. This is a principle, I think, common to Getting Things Done and Covey’s 7 Habits. If you have a goal to track your budget, get exercise, clean your house, read scriptures, play with your kids, or finish a project, make sure you do that before you start typing that post. You may find that, after finishing what’s important, you lose the energy to write the post. It works the other way too: if you expend energy to write a post at the neglect of what’s more important, you lose energy to do what’s important. Don’t let your priorities get out of whack.
2. Always give priority to sleep rather than your blog. If it’s past your regular bedtime, click Save and return to the post later. It’s always good to give yourself 24 hours of space between writing a post and publishing it anyway. I guarantee that a post written and published in haste late at night often turns into a regret the next morning.
3. Make your posts shorter. More and more I’m convinced that long posts aren’t read. I find myself timing out on most blogs after 1.5 minutes, which matches my own readers’ habits as well. If you have a long post, break it up into several posts. Or start alternating long posts with short ones. This method still keeps you in the rhythm of writing without compromising your physical health.
4. Listen to podcasts while you exercise. If you’re so addicted to blogging and podcasting that you can’t lift yourself from the computer chair to get some exercise, start listening to podcasts while you exercise. You’ll still feel like you’re immersed in Web 2.0, and while listening you’ll also be generating ideas for new blog posts.
5. Make other activities more blog-like. Let’s say you have a goal to read the scriptures each day, or to track your eating habits each day. You can give each of these activities a blog-like spin. For scriptures, I have a Ning group I created that automatically posts a chapter a day. I add my comments below the chapter/post, and friends I’ve invited sometimes participate. With weight loss, you could use SparkPeople, which includes online calorie counters, teams, daily posts, and other interactive features, to make it feel like you’re engaged in blog-like activity.

Do you have any tips to avoid the physical dark side of blogging?

Scott Abel just recently started a new social network community called The Content Wrangler Community. Within a couple of weeks, it already attracted 824 868 members. This community on Ning is quickly becoming the social network community for technical writers and others in our field.

On Ning you can –

Network with peers. Find jobs. Share information. Start a blog. Upload and watch videos. Join a group. Begin a discussion. Learn about software. Find events. Ask for help. It’s all here. Become a member. It’s free!

Getting Started on Ning

To browse the social network, visit http://thecontentwrangler.ning.com. To join the social network, click the Sign Up link in the upper-right corner.

You can visit my Ning page here. Please feel free to add me as a friend. Or, once you set up your Ning account, allow me to add you as a friend.

And if you want to create a group within the community, you can do so. For example, Anne Gentle set up a Blogging group. And I just created a Podcasting group.

I’m Excited About This

I’m really excited about this new community. Facebook is extremely popular right now, and Ning is just another type of Facebook. It’s fun to see all the new faces in there.

For all those who never figured out blogging and RSS, this community provides the same features invisibly in the background. All kinds of writers I’ve never seen before are suddenly appearing online.

More About Ning

For more information about Ning itself, check out the video below (or read more here).

This Interactive conference “celebrates the creativity and passion behind the coolest new media technologies.” Basically, everyone who is doing anything cool on the Internet ends up speaking there. 37 Signals, Facebook, Wired — they’re all there.

Many of the presentations are interactive panel discussions. Everyone twitters and blogs and texts during the presentations, etc. It’s like a gathering of the Internet geeks and hackers and designers and content creators.

Important: Because almost every session is recorded and distributed practically the same day, you can start attending sessions yourselves. Here’s a list of all the feeds available.

The interesting thing is, although the sessions are recorded and distributed freely, the attendance at the conference seems as high as ever. I haven’t seen statistics, so I’m making an assumption, but I’m guessing that attendance at the conference actually increases every year because people hear how engaging it is.

Listening to the podcasts makes me wish I could attend. The high energy, the new technologies, the experimental successes, the young entreprenuers — it looks like a big tech gathering with continual parties and meetups between and after sessions.

I wish that the STC Summit, WritersUA, Atlanta Currents, Doc Train, and the dozen other technical writing conferences that take place each year would do the same as SXSW — record the presenters and distribute them in near real-time. If I ever became STC president, I would do this. People are often afraid of the unknown. That’s what Jason Fried of the 37 Signals said in his presentation (listen to MP3). At 37 Signals, they recently switched to 4 day work-weeks (not 10 hour days), and they help fund their employees’ personal hobbies.

I’m about 12 minutes into the Mark Zuckerburg (Facebook founder) keynote (mp3). This is a must-listen-to interview, not only to hear Zuckerburg talk about the grander mission of Facebook, but to evaluate for yourself whether you think the interviewer tanked the interview.

Before you listen to the interview, read this post by Jeff Jarvis.

Jarvis writes,

She pulled some basic mistakes in interviewing. She interrupted him. The first minute of the conversation, he wanted to talk about people using Facebook to organize against Colombian guerrillas — a fascinating story — and she didn’t let him finish, trying to show that she already knew this. The real mistake was that she wasn’t listening.

… When it became obvious that the audience was hostile to her — cheering Zuckergerg when he told her to ask a question — she acted hurt, as if this hour was about her. Worse, she told us how tough her job was. It wasn’t tough. It was a privilege and she was blowing it. And at the end, when she said that people should send her an email telling her what went wrong, she was so 1994; she didn’t understand that the people in the crowd were already coalescing in Twitter and blogs into an instant consensus. Oh, if only there’d been a back-channel chat projected on the screen beside her. Then, she could have seen.

As I’m listening to the interview, in places I can see exactly what Jarvis is saying. The interviewer isn’t so bad near the beginning, in my opinion, but it’s annoying when she interrupts Zuckerburg and redirects the attention to herself.

Personally, I still haven’t caught the Facebook frenzy. Scott Abel has started an extensive community in Ning for the technical community crowd. You might want to check that out after listening to Zuckerburg.

Update: I finished listening to the Zuckerburg podcast. At about the 49 minute mark, the interview takes a really interesting turn. Definitely a spiral downward for the interviewer, as the audience rallies in a  “witch hunt” — as Michael Arrington calls it — against her. It wouldn’t have been so bad if Sarah Lacy, the interviewer, had just shrugged her shoulders at the 26 second applause for her to shut up — and then turned the questions over to the audience.

But in such a high pressure situation, she got a bit angry and confused and defensive, which made things worse for her. I wasn’t there, so my perspective is distorted, but I think the audience was immature to revolt. And Zuckerberg’s commentary wasn’t that interesting in itself — he kept saying Facebook’s mission is to help people “communicate and connect,” and also to “increase empathy” yada yada yada.