I'd Rather Be Writing » community

Update on the Search for Enterprise Authoring

Tom Johnson — Tue, 08 Mar 2011 15:36:13 +0000

So many different ways to go.

It’s been a couple of weeks since I posted about my team’s search for an enterprise authoring strategy. So far, we’re just as split as ever about the problem. It seems that you can go four separate routes: DITA, HAT, Web, or Wiki. Here are some of the paths and difficulties we’re encountering.

DITA

DITA has traction as a new standard format for help authoring, but the DITA Open Toolkit output isn’t attractive out of the box. Further, the HTML output is a far cry from the tripane help output, which we’re accustomed to seeing from traditional help authoring tools.

While DITA is a cool idea, relinquishing control over the way the help looks will hurt our chances of getting buy-in from other groups and will leave us powerless to meet the needs of project managers who ask for some customization beyond margin adjustments and typography.

Scriptorium has a DITA PDF and tripane help plugin, which looks promising (see A makeover for the DITA OT’s PDF plugin). I caught a glimpse of it in the Attractive DITA webinar. Scriptorium is up front about pricing — $10k for the PDF plugin, $4K for the tripane help plugin.

Although I like the idea of the DITA standard, I dislike the idea that I would need to be a programmer to control the output. That puts our team in a position of vulnerability that none of us wants to accept. About the only solution in the short term is to hire a consultant to make the help look decent, and then just leave it be. Leaving the output fixed does score a point for consistency, but my team is design savvy and used to being in control.

HAT

Another path might be the help authoring tool (HAT) route, using tools such as Flare, RoboHelp, or Author-it. Flare has just released version 7, which allows collaboration through SharePoint as a file repository. This would be great, since we have a heavy SharePoint environment at my work. Author-it, another strong HAT, has a mind-blowing plugin called Author-it Live that allows a logged-in user to edit the online help inline similar to a wiki.

HATs are compelling because they seem to offer a complete solution with granular control over the output. The only problem is that each author usually needs an instance of the HAT, which is about $1,000 each depending on the tool. The Author-it Live solution allows concurrent licenses to the product, so the users don’t need to be dedicated — just limited to a certain amount of users at a time.

Author-it is attractive because another group in our organization already purchased this solution (but hasn’t implemented it yet). Also, the tool is robust, which is something we welcome. But trying to force the tool on others in surrounding departments who may not be technical or open to change will be an uphill battle. It’s hard to go to other groups and say, Here, buy our tool, learn our ways, use our output profiles when they already have a simpler solution that seems to work for them.

Web

Neither DITA nor HATs provide a Web 2.0 output. We’re all conscious of the fact that tripane help is a relic of 1995, and invites as much confidence in users as a station wagon. While Sarah O’Keefe suggests that actual user standards for document design are probably below our own — that is, users are more interested in the content, not so much in how it all looks — we want our help to fit in line with the current century.

Many web content management systems, such as Drupal or WordPress, provide an abundance of web elements that speak the same language as contemporary Internet users. Categories, tags, comments, RSS feeds, most popular posts, multimedia, jQuery — it’s all available in one experience in a website format.

The problem with these web CMS formats, though, is that you sacrifice content re-use and printed output. At most, a topic on a web page may be printable by itself. Web developers don’t care about re-use, so this is not a feature you’ll find.

We were excited to see that EasyDITA exports to WordPress, even though such an export from DITA is already available through a free plugin. Unfortunately many organizations, including our own, don’t support MySQL / PHP solutions. And even if they did, we’re skeptical that a WordPress theme could offer a navigation-friendly table of contents for hundreds of topics. And once you output to WordPress, there’s no round-tripping back into EasyDITA.

Some developers in our organization actually built a WordPress-like CMS, which they use to run the Newsroom. Amazingly, it uses our Mark Logic XML database on the backend, so theoretically we could write some XQuery scripts to get the content re-use and printed output that we need. But none of us knows how to do this, and we’re not so excited to adopt an XML solution that doesn’t involve DITA.

Wiki

Wikis such as Confluence and Mediawiki have appeal because we do have a large volunteer community. We’re already using Mediawiki for these volunteers, and it seems to be working in some areas. For example, the LDSTech wiki has regular contributors, and FamilySearch apparently has 50,000 Mediawiki pages with genealogy content.

I love the ease of collaboration that wikis offer, but they do a poor job with traditional help authoring requirements, such as selective re-use, access control, multi-channel publishing, and so on. Wikis can be styled with a Web 2.0 look, but most wikis I see are sprawling atrocities with column widths spanning the entire length of the browser, and no attempt at a table of contents.

Also, it seems that I am the only person on my team even remotely interested in wikis. On top of all this, I struggle to make community efforts worthwhile. (See my post, Do Community Efforts Work?)

Wikis do have a strong pull, though, since our organization wants to move more toward community integration in the future, with goals as ambitious as having 80 percent of the work done by volunteers.

Future Requirements

The most troubling problem in our enterprise strategy is that we’re pursuing a solution based on hypothetical requirements. There isn’t currently an enterprise-wide authoring practice, so finding a tool that is easy to use, collaborative, standards-based, cost-effective, and has attractive PDF and web output is based on the idea that people in various departments will actually adopt our solution and fall into line with the new methodology.

Our next big question is this: Once we select/compromise on a tool, how do we take it enterprise-wide? We don’t want to push the issue too early, or we’ll get every tribe vying for his or her own preference. If we get our own house in order and push our solution after figuring out what it is, we risk formalizing a solution that doesn’t meet their needs or wants of all the surrounding departments. We may end up with an approach that is designed for the enterprise but in reality is only used by us.

————-

photo by Christine Selek on Flickr

Blog Sponsors

Do community efforts work?

Tom Johnson — Tue, 14 Dec 2010 15:32:11 +0000

Some of my projects include community-involved documentation. When you work for a church, it’s not hard to find dedicated members willing and committed to sacrificing a few hours for a higher cause. To harness community efforts, I gathered up a large pool of volunteer names and formed a listserv. I communicated project needs with the listserv members and asked for help.

Despite some contributions, the majority of volunteers are hindered by too many obstacles — access to information, time, standards, and more — to contribute much. As such, I’ve begun to change my expectations from content creation to content review and feedback.

Access to Information

The community volunteer, as an outsider, faces difficulties accessing the right people and information. As a volunteer, you may not know the project manager, the quality assurance lead, the developers, and other contacts that have information you need. Without access to the right information sources, documentation efforts are vain.

If you do have contact information, you may be contributing only in your spare time, outside of regular working hours. So you’ll be left with email and voicemail exchanges, if you’re bold enough to even make contact. If you’ve ever tried to get information when no one is in the office, you know how frustrating that can be.

Trust also becomes an issue, because many times project information is sensitive or still in deliberation. Project managers may be hesitant to disclose the full facts to an outsider they don’t know, whom they’ve never met or worked with.

Time and Sequentiality

Another problem is time. Many volunteers have full-time jobs, families, and little time. The idea with volunteer work is to harness the long tail: if 100 volunteers each contribute two hours in a day, that’s more than a month of labor of one full-time employee. The problem is, tasks often cannot be chunked into two hour increments that can be done independent of a specific sequence.

Think about designing and creating a quick reference guide, or configuring an online help. The tasks can’t be broken down into two-hour chunks that can be created by different people at different times. Many times tasks are sequential — they build on one another. You must first gather the information, then organize it, then illustrate it, then lay it out, then review it, then test it, then publish it, and and so on. The whole work may take 200 hours to complete, but each phase builds on the previous one, more or less, so distributing the entire work to the community would require that you spread out the work in phases. This kind of coordination is tough and complicates volunteer efforts.

Style and Standards

Another problem with community contributions deals with style and standards. I’m a picky writer, and anything the community produces will be perceived as coming from my group, or me. If a deliverable doesn’t match my standards, style, or preference, I’m less inclined to support it. When a volunteer submits what I feel are sub- or non-standard deliverables or content, I face an uncomfortable situation that I’m not sure how to handle tactically — offend the volunteer by refusing the work, accept the work and lower confidence in my team, or spend time reworking the deliverable to my satisfaction, which may require more work than creating it from scratch.

It’s impractical to expect volunteers to be familiar with the intricacies of our department’s style, to know my own preferences for formats, etc. I might as well expect a writer from another company to magically match the style and approach of our own.

Management Time

In working with community, you also have to consider time for volunteer management. Expect to spend about 25 percent of your time communicating, responding, and managing community member questions and tasks. This is somewhat of a risk, because you assume that the results from the community will surpass what you could have done yourself in that 25 percent of time. Management may not be something you can bill towards, especially if you aren’t already a manager.

Further, management is complicated by the remote distance. You’re managing people you’ve never met, working with them without any idea of their background, or without understanding their expectations and motivations. You could be managing your neighbor, or someone in an island in the Pacific, or a retired army colonel — all with little understanding of their background.

Success with Reviews and Feedback

Where community efforts have succeeded for me is with reviews and feedback. At times, when I finish a page of documentation and publish it to the wiki, I often send out an announcement to the community listserv asking for their review. Their comments sometimes triple the depth of the original article. Community members pose tough questions, present perspectives I hadn’t considered, note situations I hadn’t thought about, and generally scrutinize the information available.

Having a sounding board of 65 intelligent people is not something to underestimate. Sometimes I’ll just throw an idea out to them to get their thoughts. Other times their non-response tells me information too — for example, that something is not an issue for people.

On the left, the content is already written; on the right, the page is blank. It's a lot easier for volunteers to provide feedback than to create raw content.

Although community members may be reviewing a specific collection of pages, it’s rare that they make edits directly. More often they send a response with some suggestions and questions, and prefer that I make the edits. I prefer this method too.

Super Volunteer

So far I’ve been speaking generally about my experience with typical community volunteers. But for every 100 volunteers, there are a few who are golden contributors. Their efforts far exceed the efforts of normal volunteers. They go above and beyond the call of duty with a feeling of personal ownership and dedication. I don’t exactly know what motivates these super volunteers, but I love them.

Last week we were facing a tough decision about where to publish information to avoid duplication, so I consulted with a super volunteer. His response was thorough and insightful. Not only did he provide a sound reason to help me make a decision, he also pointed out a problem with terminology that I hadn’t considered. I ended up reworking and re-organizing the content.

This example reinforces the best benefit I’ve received from community efforts: feedback and insight. Rather than inviting community volunteers to make direct edits and create raw content (and then get frustrated when they don’t participate), I’m now more inclined to invite them to provide feedback and insight, to review and comment. I ask how they would handle a situation. I ask if a specific page I wrote seems clear. I ask if a topic covers all the issues they face with a task.

With an expectation of feedback and review, rather than raw content creation, I’ve had a lot more success with community efforts. Trends with minimal participation fall away, and the sound of the community voice increases.

Blog Sponsors

The Role of the Gatekeeper

Tom Johnson — Wed, 28 Jul 2010 06:04:27 +0000

Sarah O’Keefe’s guest post — The Role of the Gatekeeper is Changing — on Peg Mulligan’s blog is interesting. Sarah writes,

The Internet is removing the traditional gatekeepers for content.

This may seem obvious, but its implications in my life have been profound. I majored in English and then earned an MFA in creative writing. After graduating, I gathered up my best essays and sent them off to literary journals for publication. After months of waiting, I didn’t publish hardly anything. It was frustrating. They were good essays, but they didn’t have the right focus. That timeframe was about 1999 to 2002.

A few years later, I started blogging. First in an experimental, non-committal way. Then I started to gain more focus, and after a while, I realized that I could have as much satisfaction publishing online on my blog as I could in any print journal.

I realize Sarah’s comment was in the context of technical communication, but the principle is the same. Whatever you want to publish, you can. There are almost no restrictions on the Internet. Collaborative platforms empower even the most technically illiterate people.

Sarah writes,

There’s never enough time for in-house professionals to create all of the content that’s needed. Contributions from the user community can provide additional support and build on the official core content.

This statement is more relevant to me now more than ever. I was enthusiastic about a particular project at work, and two weeks into it, the budget dropped. I have to take my half-written help content to the community to help finish it off. And while I have volunteers, I realize that I need a solid collaborative platform with clear directions, easy tasks, and a lot of management and feedback to be successful with community efforts. All my previous efforts to involve community in writing documentation have mostly failed.

Sarah writes,

There is a temptation for business executives, especially in cash-poor start-ups, to dismiss their technical communication staff and simply rely on the community to provide documentation.

This trend always astounds me. Even in my organization, support for professional technical writers varies significantly from department to department. On some projects, the customer (in a specific business department) has a designated writer who handles the material. On other projects, we (the IT department) provide help. But it always frustrates me to see a project manager marginalize help and dismiss the technical writer’s role. In fact, I need to meet with a project manager tomorrow to try to talk sense into him.

Blog Sponsors

From Overlooked to Center Stage [8]

Tom Johnson — Sun, 18 Apr 2010 06:30:22 +0000

Catalyst 4: Wiki Manager

As if I wasn’t already doing enough, I also started to wear another hat: wiki manager. It turns out I failed in this role, but I’ll still include it here because it segues into another topic I want to explore, which is spreading yourself too thin.

At the beginning of this essay I mentioned the community projects we started up. When you work for a nonprofit organization, especially a church, which people can feel a higher cause about, community members are often willing to dedicate their free time towards volunteer projects. If the Amish can pull together a community for barn-raising, and the early saints could sacrifice one day a week to build a temple, we could pull together an equivalent volunteer workforce to build a software application.

And it worked. Community developers volunteered their time to build applications. Community interaction designers volunteered their time to build interfaces. Community quality assurance engineers volunteered their time to test the application. And even community technical writers volunteered their time to write documentation for these applications.

Coordinating the technical writer volunteers — assigning them to projects, helping them to get started, oriented, and moving forward with documentation — is something my colleague and I were asked to do. It was a new role we were to play.

As the emails about volunteer efforts trickled in, I helped a few writers get started. I thought I could point them in the right direction, make sure they had access, and just check on their work every once in a while. In this way, I could help oversee the writing of dozens of projects. I could expand my capability to work on more projects, leverage more help material, and eventually build a small army of volunteer technical writers that I could count on to write documentation for virtually any project overnight.

It was a naive idea. I underestimated the time involved in management, especially management of remote, often inexperienced volunteers. The first real contributor was slow to start, needed extensive hand-holding, and got offended when I edited (actually renovated) his contributions. One day he just disappeared.

I realized that I spent more time trying to manage the potential writers than it would have taken me to write the documentation myself. I also spent weeks creating the wiki skin for the projects, branding it with the same look and feel as the home site.

We didn’t have a formal style guide or a specific documentation approach. The freedom that comes with the flexibility I found so liberating also proved to be debilitating to these remote volunteers. The technical writing component of the projects just didn’t take off. I neglected the projects due to deadlines with other projects. I eventually fell out of touch with the project managers and community, and before long, the documentation was completely absent.

My experience working as wiki manager with these community projects led me to wonder if I hadn’t come to a point where I was spreading myself too thin.

Blog Sponsors

Together or Apart: Collaboration Models for Technical Writing

Tom Johnson — Tue, 23 Feb 2010 04:37:42 +0000

Today I spent a rather lonely day writing documentation. I had one team meeting, during which our team gathered for what seemed like a brief second. We then departed back to our respective portfolios, most of us working alone and in solitude toward some distant documentation goal.

Some writing teams sit together. They chum with each other all day long about commas and online help layouts. At my first job as a technical writer, I sat in a long row of cubicles we figuratively called “The Technical Publications Office.” All day long I could listen to my colleagues say things like “Oh my goodness, this guy is writing fused sentences.” Or “Don’t you just love it when all your images disappear from Microsoft Word!” or “Hey Tom, can you help me with something?”

You know what I’m talking about — the camaraderie of being in a group of writers, exchanging comments about projects, bantering about this or that. It’s a cozy, comfortable feeling, being surrounded by other literary kind.

Agile Environments

It’s not like that in my current agile environment, though. In many agile environments, you have to forge your own way, often sitting away from your writer colleagues, embedded among QA, developers, interaction designers, and managers on a project team. Although I’m on a team of eight writers, most of us are spread out in different departments, assigned to different projects. As a result, writing documentation can often be a lonely, long experience alleviated only through Pandora, Twitter, IM, the incoming comments on my blog, and my wife’s scandalous posts.

I know it would be a lot more fun to be desk-to-desk with all the other writers in the organization. We could stop every now and then to feign horror at grammar atrocities or mock the edits our SMEs make. We could easily review each others’ work, provide feedback about parallelism with topic titles, compare TOC layouts, or discuss the style guide.

But I’m more effective sitting next to other employees working on the same project. Sometimes I wear a QA hat and point out bugs (and explain/show them to developers). Other times I coordinate with project managers about customer feedback and concerns. Other times I ask developers to explain how something works or why they built a function a certain way. You need to be close to your project team to interact with them, right? Proximity has an impact on communication, no doubt. But I’m not so sure ours is the best model to follow.

The Book Sprint Model

Last month leaving an STC meeting, as I was walked through an windy parking lot to my car, I caught up with a colleague, Joe, who works as the sole technical writer at a nearby company.

We talked a little about the meeting. And then he said, “Sometimes I have so many questions. I mean, do you ever think we have the whole model wrong?”

“Huh?” I said. “What are you talking about?”

“You have eight writers in your team. Why don’t you all just sit down and tackle a project together and knock out the documentation in a week?”

I’d heard of this model applied to book sprints with open source projects. Anne Gentle has written extensively about book sprints. Tomas at BookSprint Central explains that coming across the idea of the book sprint was the “most important epiphany of [his] professional career.” He explains how few people rarely have the time to sit down and write an entire book themselves. It simply never gets done. He says,

I also knew that there was no way i was going to be able to spend all my evenings for a year writing such a book even if i wanted to. Which i didn’t. And i had a feeling that while i’d collected a network of incredibly smart people, with boundless experience in this field, everyone else felt mostly the same as me when it came to evenings and years. But I also knew that i could convince almost anyone of these incredibly smart people to give away a week of their time to such as good cause. So there were the constraints. Have: One week of time each from a bunch of smart people. Need: Finished book.

His solution was the book sprint. And it worked. He flew in a group of smart, knowledgeable people and sat them down in a room for a week to write. They produced a completed book, which was downloaded thousands of times and translated into numerous languages.

I like the book sprint idea, quite a bit. It reminds me of the Amish barn raising, or a group of guys pulling together to help someone move.

In fact, as far back as 2005 at a conference in Raleigh, I remember Rick Sapir arguing against the one-writer-for-the-entire-project model that’s so common in documentation. Why not have several writers work on various parts of documentation? he said. Everyone takes a little chunk of the application and writes documentation for it. The idea that one writer creates all the documentation for a project is an old model, he explained.

At the time, I disagreed. I said it wouldn’t work because you can’t write effectively about one aspect of an application without understanding the whole. And to understand the whole takes months of exploration and learning. Not to mention the dozens of project meetings. If everyone has to devote the same amount of time learning the application to write about one small part, isn’t that inefficient?

I’m also wasn’t sure how help can be put together in such an independent way. Although each topic in a help system is usually a semi-independent chunk, how do you know that the topics Writer A contributes don’t overlap, contradict, interfere, or otherwise jar with the topics that Writer B contributes?

On the other hand, the group collaboration model has its benefits. Multiple writers working together can see an application from various points of view. The writers are less inclined to become myopic and routine. They can more freely bounce ideas off each other, make more informed decisions about content and layout, and generally approach the application with twice the brain power.

Book Sprints with Community Projects

One day I’d like to try the book sprint model in a corporate setting. However, since major changes within a large organization are hard to implement, it might be more practical to do a book sprint with our community development projects. We have more than a dozen community-driven projects (most of them small) in which the community participates in the requirements, development, and design. This is one of the cool and interesting aspects of working for a nonprofit organization. Some members want to volunteer their time and talents to further the work. We’ve been trying to figure out a way to harness their talents.

Previously, I had been pitching the incentive to contribute tech docs as an opportunity to get experience for your portfolio. But that route wasn’t so effective. Participation was slow and inconsistent.

Next time, I might contact 10 or so community colleagues interested in helping out and invite them to participate in a book sprint. It could be an entire day, one that we dedicate to documenting just one project. An entire Saturday, or something. I doubt I would fly people out to Utah and put them up in a hotel room for a week, because most people can’t take a vacation from their regular jobs for this, but I can see people dedicating a Friday or Saturday or even Sunday to remotely contribute toward a project they believe in, especially if the idea is packaged in the conceit of a “church book sprint.”

Whether you’re integrated into an agile project team and away from other writers, or together with multiple writers on the same project, increasing collaboration is key. Rick was right: the single writer working tirelessly in solitude on a manual that he or she authors from start to finish is dead.

Blog Sponsors

Fragmented Communities and the Chapter/SIG Web Site Problem

Tom Johnson — Mon, 01 Feb 2010 15:33:18 +0000

Recently Will Sansbury and I gave a webinar to STC community leaders on chapter and SIG websites. Rather than giving a static, one-way presentation about theoretical concepts with web design, or boring people with technical details they probably didn’t care about, we held the webinar more like a design review workshop, not too different from a writing group workshop.

Although I spent three years in a creative writing program holding exactly these types of writing workshops, in which a group of people provide feedback on the story or essay someone submits, it never crossed my mind that designers probably sit around tables doing the exact same thing with websites.

Design Reviews

Regardless of the topic, the methodology of the workshop is mostly the same. In a tactful way, you explain what works well and what could be improved. Others either agree or disagree with your analysis, and hopefully they explain why. The only difference between critiquing creative stories and websites is in the questions you ask. Rather than ask, what’s the story here? Are the characters believable? Does it have arc? You ask questions about findability, simplicity, readability, and so forth.

I found that in looking at websites, my feedback could be grouped into about seven categories:

Purpose

What are you trying to achieve with the site?
What do you want the audience to do on the site?
What do you want feedback about?

Findability

What are some things your users might be looking for? Is it easy to find them?
If you search for something, are the results accurate?

Simplicity

Is the site navigation simple to understand?
How does the site handle submenus to provide additional information?
Is the site busy?
Is there enough white space in the site?

Readability

How easy is it to read the content?
Is the font size, column width, leading, and typography working together in a readable way?
Can I subscribe to the content with Facebook, Twitter, RSS, or e-mail to read it in the format I want?
Are the paragraphs small, broken up with lists, blockquotes, and other formatting varieties?

Interactivity

Can I add comments on things I read?
Can I read other people’s comments and reply to their comments in a threaded way?
Can I contact someone through an email address or contact form? If a contact form, do I know where it goes or if it sent correctly?
If I have a job to post, can I submit the details myself? Can I even post it myself?

Content Appeal

Is the content interesting to read?
Is the content current?
Can multiple people author and maintain content, so that all the burden isn’t placed on one person?
Do you integrate your news into real-time articles/posts on the site?

Design Appeal

Where do my eyes focus naturally focus on the site?
Are there any design element repeated?
Is the site attractive to look at? Why or why not?

For more on running a design review, see Scott Oberkun’s How to Run a Design Critique and Makiko Itho’s The Delicate Art of (Web) Design Critique.

Trends from the Analysis

If you go through each of these categories, you usually find something worthwhile to say. We analyzed six different sites: Quality Process SIG, Twin Cities, Heartland, Tech Editing SIG, Orlando, and the Contracting and Independent Consulting SIG.

The webinar description suggested that we would explore ways to build attractive online sites where members could interact and find value, because fewer and fewer people are physically gathering for meetings.

As we moved through the sites, it was clear that a lot of people were trying to move in exactly this direction — towards collaboration and participation. The Quality Process SIG adopted SharePoint to make it easy for numerous people to author content. Twin Cites integrated a social networking component in a custom CMS where members could friend each other, add personal details, and even write blog posts. Orlando was in the process of moving their content to WordPress because their old site was a “dinosaur.” The Tech Editing SIG built their content on a wiki platform containing a section that showed posts from their email list discussions in an automated way.

What’s Missing

To enable participation and collaboration, many of the platforms allowed you to comment, subscribe, interact, log in, and manage the content. This makes sense.

But the platform is only the first step. Whether you’re using WordPress, Drupal, Joomla, SharePoint, Ning, or any other Web 2.0-capable technology, a larger ingredient is missing from the recipe for a thriving online site where members naturally gravitate to for interaction. Your site can be as interactive as anything can be, and yet still remain dormant, unused, unexplored, rarely visited, and rarely even noticed unless you provide a reason for people to come together as a community.

For example, although the Twin Cities site offers the ability to friend others, blog, and add personal details about your location, interests, and other details, it isn’t generating the activity you see on Facebook.

What’s interesting about Facebook isn’t that it allows you to write on other people’s walls, provide status updates, or add other people as friends. What’s interesting is that so many people are on Facebook, checking it and posting to it daily or even hourly.

Is it possible to create an online platform that technical communicators would use with as much popularity as Facebook or Twitter or even Stack Overflow?

The problem, I think, is in gathering a critical mass of community. Chapters are so small, it’s hard to see much activity from members on a site. For example, our chapter now has about 20 members (as opposed to about 75 from last year). To think we’ll convert the site into a thriving hub of online interaction is an illusion. You need thousands of people to build up the exchanges that take place in a popular community. When you have the thousands of people coming to your site every day, they begin to interact, and the interactions fuel more comments and replies and posts. At some point, you have a thriving community. But you don’t build a community without a critical mass of participation.

Without a critical mass of people to form a community, you end up with a dormant-looking site — for example, what most chapter sites look like.

The Ning Community Scott Abel created comes closest to the thriving online site where members can interact, but even that site seems underused. I just logged into the other day for the first time in months.

Again, the main problem is in the critical mass. There just aren’t enough people in chapters to form a presence on a site. Chapters and SIGs fragment the already small online technical communicator audience.

Additionally, although SIGs have greater potential for online interaction, most of the activity is often better expressed through e-mail listservs and threaded forum discussions. As old-school as email or forums are, they’re fast, immediate, and reach almost everyone.

The Solution?

I’m not really sure what solution is for chapter and SIG sites to move from dormant sites to thriving hubs of interaction. Technical writers are a small niche of overall people on the web, and when you fragment that already small niche into even smaller groups of chapters and SIGs, they never seem to come together in a critical mass of people.

This problem isn’t unique to our group. It’s a problem that stems for many independent publishing locations and sites. Conversations are taking place on blogs here and there, email listservs here and there, forums here and there, and the consequence is a bunch of whispers that you can’t hear (unless you look in each of the individual places).

I believe the solution won’t involve centralizing the information/people into one site and location. Instead, it will involve aggregating the sources through RSS and other technology.

Blog Sponsors

Design Reviews and Posting Without Answers

Tom Johnson — Mon, 09 Nov 2009 01:07:22 +0000

Recently our technical writing team at work (Information Strategies and Design) started holding regular design reviews. The review sessions are patterned after meetings that our interaction designers hold regularly, in which they get together and critique each others designs and approaches toward user interfaces.

In our design review sessions, a couple of members from our eight-person team share what they’re working on and ask questions about challenges they’re facing. We provide feedback and critique their project.

These design review sessions are one of the coolest things we’ve done as a team. We don’t have a strict team style guide or set of standard deliverables. (We do follow the Microsoft Style Guide and, at times, a thin organizational style guide.) But as far as branding the help material, there can be a lot of variation among the online help files, quick reference guides, landing pages, context-sensitive help, interface text, e-learning, video tutorials, or other help materials we create.

If you’ve ever participated in a creative writing group, the design review works similarly. Team members use common sense and experience to guide their questions and reviews. Somewhat in contrast to a creative writing group, though, you don’t have to bring a finished piece to share.

For example, the other week I was coordinating who would share materials for our design review, and one of our team members told me he wasn’t ready to show it. What? I said. The design review is not about showing finished material. It’s better, in fact, to show what you’re currently working on, while it’s still early in the process, before you’ve cemented everything. Oh, he said. In that case, yes.

Parallels with Blogging

I find that the same mindset works with blogging as well. Often times we think we can’t publish a post until we’ve finished a cool thought, or until we’ve finalized a solution to something. But this past week, I added a couple of posts in which I wasn’t quite sure what I thought. In my Theme Parks and External and Internal Input post, I was only part way into a thought. Commenters added to the discussion and helped me better see insights and perspectives on the issue.

I also wrote a post on working with wikis, A Few Surprises in Using a Wiki for Documentation. I’m not an expert on wikis, especially Mediawiki, and there are many things about wiki authoring that I need to learn. But this didn’t stop me from posting about it. Instead, I shared some of the challenges and issues I was facing. And some of the commenters added information that proved incredibly helpful. For example, see this informative comment by Amalia.

Had I waited until I finished in putting together an entire strategy and methodology for authoring on Mediawiki before posting about it, I would have missed out on the guidance and direction early on. It’s from the helpful information early in the process, particularly with challenges I’m facing, that comments on a blog become the most useful. A blog is, remember, a journal, so it contains thoughts and ideas and experiments in progress — not always finished solutions, completed ideas, or tried-and-true methodologies.

What’s true in design review is just as true in blogging. Sharing the current challenges you’re facing will make your experience in the blogosphere or design review process more helpful and rewarding.

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

How Do Blogs and Wikis Fit Together?

Tom Johnson — Tue, 08 Sep 2009 06:10:55 +0000

Although many people put blogs and wikis in the same social media category, blogs and wikis are actually quite different. Blogs are individually authored mini-magazines or journals where one author (or sometimes a small authoring group) crank out article after article (or entry after entry) usually with a common theme. After each article is published, the article is considered done and the author moves on to newer pastures, always hunting for the next story, formulating the next insight, thinking about the next post. Readers can comment and subscribe by RSS.

Wikis, on the other hand, are a platform for groups to collaborate on an information project, such as documentation, technical specs, or other reference material (e.g., Wikipedia). One author isn’t just cranking out all the information. Multiple authors are contributing chunks and pieces, linking from one page to another, making edits on each other’s content, diving deeper where necessary, and moving toward the idea of a more complete information product. Wikis are rarely ever done. They are successful only as much as they tap into the collective intelligence of a group.

How exactly do these two formats fit together? In [amazon-product type="text" text="Conversation and Community"]0982219113[/amazon-product], Anne Gentle says that the blog can often be a conversation starter, the medium that opens up communication among people. Your blog can attract outsiders and draw them in to participate on a wiki or other involvement.

Seeing how these two formats and activities fit together provided an Aha! type of moment for me last week. We have a community projects wiki where a lot of developers, QA engineers, and others interact on a technical level, either compiling requirements, designs, or other details about the projects they’re building. The site also has a blog component, but the blog doesn’t always address the existing projects. In fact, the blog mainly consists of random IT topics written by people in our department.

I realized (not that it’s really much of an insight) that in this situation, the blog should act as a companion to the wiki. While the wiki has project details and other specs, it’s not the motivational piece. It doesn’t build trust, inspire people to join the community, or even communicate that much to those outside of the layers of its structure. Just as a charter or project requirements documents rarely inspires anyone to volunteer for the project, the same might be said of wikis. But that’s not the wiki’s job. It’s the blog’s job. The blog serves as the human-focused news stream for sharing announcements, insights, developments, stories, and other details about the projects going on in the wiki. They’re a perfect fit, and one fuels the other.

Blog Sponsors

Podcast with Anne Gentle about her Conversation and Community book

Tom Johnson — Wed, 26 Aug 2009 13:39:41 +0000

[amazon-product align="right"]0982219113[/amazon-product]

Download MP3
Length: 40 min.

As a follow-up to my review of Anne Gentle’s book, [amazon-product type="text" text="Conversation and Community: The Social Web for Documentation"]0982219113[/amazon-product], I also interviewed her for a podcast. Now you can listen to Anne talk about some of the concepts in her book in a more personal way through the headphones of your iPod. In this 40 minute podcast, we cover questions such as the following:

What’s the first step in connecting with your users?
Why are wikis used more internally than externally?
How can you build trust with users?
What’s the 90-9-1 percent rule and how can you change the 1 percent part?
What three steps can you follow for any strategy with social media?
What is “read wear” and how can you make that content more visible?
What happens when you break the listen-participate-share-then-lead model?
How can you use Twitter into your documentation strategy?
What mindset is antithetical to building conversations and communities with your users?

Additional Resources

Companion site to Conversation and Community on XML Press
Anne Gentle’s blog
XML Press
Tweets converted into T-shirt themes
Posts about Participation Inequality (the 90-9-1 rule)
Sarrah Maddox blog
Stewart Mader
Review by Jefro
Review from Sarah Maddox. (Sarah’s post also lists other reviews.)

To contact Anne, see the contact button on her blog, Just Write Click.