I'd Rather Be Writing » Wikis

Confab 2012: Thoughts and Reactions

Tom Johnson — Sat, 19 May 2012 22:39:26 +0000

I recently attended Confab in Minneapolis. I was one of about 5 technical writers among the 650 attendees, which is why I found it surprising to hear Kristina Halverson say, We can learn a lot from tech comm. Let me repeat that. We can learn a lot from tech comm.

I felt pleased to hear this shout-out to my profession, and then tried to unpack exactly what she meant. Throughout the conference, a number of presenters emphasized the need for structured authoring. This refrain seemed loudest in Karen McGrane’s talk on Adapting Ourselves to Adaptive Content (a presentation she is also giving at the STC Summit).

I believe they respect tech comm for our expertise in structured authoring, which theoretically gives rise to an ability to publish many different outputs from one source. If you can publish to web, mobile, tablet, flipbook, print, intranet, blog, white paper, social media, brochures, and other content from one source, because you’ve tagged that content in the right way, then you have a strong competitive advantage in the marketplace. Yes, “structured authoring is definitely the way to go” was the message I kept hearing.

If you want to write your content once and “spray” it (to use a verb I heard in Karen’s presentation) to a dozen different publishing destinations, then you need to structure your content with the right tags, metadata, and other semantic markup to make it flexible and adaptable to the platform and context it resides on.

Despite all the enthusiasm for structured authoring, I didn’t hear much about the nitty-gritty technical details. In fact, in one presentation, the speaker talked extensively about metadata, and had us map out a taxonomy for a website. The idea was that through metadata, the content management system (CMS) would dynamically pull content into various spaces on the website based on the metadata and content model rules.

I guess sticking with concepts is fine, but I would have appreciated some refreshing realism about the difficulty of doing this. Does a CMS that pulls different objects based on metadata require about 100K and a team of programmers to implement? Or are we talking about something much simpler here?

And to write once, publish everywhere, do we have a dozen or so custom XSLT transforms to manipulate XML-tagged content into different outputs? From what I’ve heard, setting these transforms up requires developer-level expertise, and getting the PDF deliverable is so difficult that the most one can hope for is a plain-looking output that is merely acceptable rather than downright ugly. Or is responsive design the model instead?

Two words I didn’t hear

The Confab conference had many top-notch sessions. I listened to Lou Rosenfeld, Jared Spool, Mailchimp content strategists, and other well-known people. Their sessions were lively and memorable. However, I must confess that I was disappointed not hear the words “collaborative authoring” or “blog” during any presentation (except maybe as a brief word on a slide).

Why are these two concepts downplayed? First, I do not think the content strategists who attend Confab have any interest in wikis or collaborative authoring. From what I can tell, most attendees are content strategists in their organization, which usually means they write/edit/review the copy for their organization’s website and other collateral, provide a style guide, and help in myriad other undefined ways. (To be honest, I’m always a little curious to hear what people who call themselves content strategists actually do in their organizations.)

I can understand the absence of discussion around wikis, because wikis are more the domain of tech comm. Wikis are more suited for technical publishing, when you regularly interact with subject matter experts, work with constantly changing information, follow an agile methodology, and draw knowledge from product users. Wikis are not typically for marketers.

But why no discussions about blogging? In fact, no sessions scheduled for the STC Summit address blogging either. What happened to blogging? Is it simply aggregated into a larger umbrella of social media? Is blogging now just considered another form of content? Or has the unthinkable happened — has blogging become … passé?

It wasn’t too long ago that it seemed blogs were discussed more directly, and as a powerful, new form of content, rather than simply another form of social media. Where else can you publish thought-provoking, idea-soaked content with a personal voice and transparent tone? Few forms of content do more to build relationships, increase visibility, and spur interaction than a well-written blog. After all, not to call attention to myself, but MindTouch did name me #1 most influential in tech comm this year – not for my content strategy, or for any books I’ve written (which I haven’t), or for a preponderance of tweets, or for speaking engagements, or webinars, but rather for my blog.

And yet, ironically, having a blog nowadays doesn’t have nearly the impact it used to. Now pretty much everyone has a blog, even though they may not post to it more than quarterly. And the quality of the posts? If it’s a blog, it seems you’re allowed to drop the quality several notches. You don’t even need to proofread or spell check your content, really. It’s just a blog. Synonymous with blah.

In one session, Erin Kissane presented a session on “Ideas Worth Stealing.” She looked at innovations in writing and reading. Near the end, she mentioned a new site she has developed called Contents. Contents is an online magazine focused on content strategy.

From what I can tell, the style follows a similar approach as A List Apart. The site runs on WordPress, has a weekly publishing schedule, favors longer articles, probably includes an editorial workflow, has a list of regular contributors/editors, and is packaged in a responsive theme (making it mobile/tablet friendly).

Now, in looking at Contents, how is it really different from a group blog? One point Kissane made during her presentation is that lines and boundaries of content are blurring. What does it even mean for a book to be a book, now that you have mobile versions, online web versions, flipbooks, and so forth? What defines content as a book in this digital age? How does a blog post differ from a magazine article? Maybe it’s better just to refer to it all as “content.”

I like Kissane’s style, and I definitely welcome the new Contents magazine. I just don’t want us, in all this talk and praise of content, to forget about blogs.

Vivid = Verbal + Visual Interdependence

Let’s switch gears a bit. Another major focus during Confab was the emphasis on adding visuals to content. Dan Roam gave one of the most energizing keynotes I’ve listened to for a while. It was one of those keynotes where something clicked inside of me.

I used to be more gung-ho for visual illustration (see my 10 post series on visual imagination). During Dan’s presentation, I kept thinking back to my post on VITA (Video – Illustration – Text – Action) as my answer to the evolution of how one should do help content.

Somehow, in the busy-ness of life, I’d forgotten about the importance of visual content. Dan Roam reminded me of what I’d forgotten. Thank you, Dan. I was also pleasantly surprised to find a complimentary copy of Dan Roam’s latest book, Blah Blah Blah: What To Do When Words Don’t Work in my free Brain Traffic tote bag. (The conference staff really knows how to put together a nice conference.)

Dan’s main premise is that you must combine the verbal (words) with the visual (pictures) to make your ideas vivid (hence the acronym).

I also attended a session on comics by Kevin Cheng. Comics are just sequentially told visuals, usually in story form. Kevin continued some of the points Dan made, but applied them in different ways.

If I were to combine more visuals with my writing, the appeal of my content would triple. The tragedy of tech comm is that we’ve focused too much on authoring efficiency over the past decade, rather than trying to solve the problem of why so many users find help useless. If help were more visual (and I’m not just talking about inserting more screenshots), both with the illustration of concepts and with videos, I think users would welcome help material, arms wide open.

By the way, I think some of Roam’s ideas about connecting text with visuals ties back to Robert Horn’s Visual Language: Global Communication for the 21st Century. More on that later (when I finish reading Blah Blah Blah).

On the Ride Home

On the ride home, I thought I was done with Confab, but the flight attendant saw my Brain Traffic tote bag and, somewhat stunned, asked, “What’s that about – Brain Traffic?“ I thought a minute, and then said, “It’s a writer’s conference.” (Who wants to explain content strategy to a flight attendant?)

Well, it turns out the guy sitting next to me was a Confab conference attendee, returning to Colorado. We chatted for about an hour. He had a lot of great insights and feedback about the conference. One of his criticisms was a lack of dissent during the conference. Few people disagree about anything, he noted. And you know what? He’s right. I’m starting to get sick of tweets and blog posts that do nothing more than agree, praise, repeat a quote, and bemoan how others in their organization don’t get it.

What exactly would you disagree with, I asked? He mentioned Ann Rockley’s talk on governance. In the web publishing world of his clients, implementing a governance board that meets regularly to review content guidelines would be something his clients would downright laugh at. They have a need to publish immediately and regularly, without any kind of structure that introduces more bureaucracy into the system. Many of these companies aren’t big enough to merit a “governance board.”

He also pointed out that the idea of writing once and publishing everywhere was a flawed idea. You can’t publish the same content that was intended for a blog post in a white paper, a tweet, and a brochure, he explained. Different forms require a different emphasis, style, and approach. To think that you can create content that can live everywhere and anywhere because you’ve tagged it intelligently is nonsense. It doesn’t fit the world I live in.

We then got to talking about some of his projects. He is in fact a bonafide content strategist, and has begun his own company doing content strategy. He quit his regular job to do this, and has had good success so far, since the competition is scarce in his area.

With one of his clients, he explained that they publish regular blog articles to attract new readers. Readers are pulled in by the blog articles, and they are then presented with contextual links for the services the client sells. He said it has been a very successful strategy for the client. He didn’t think blogs were passé, and he was a little surprised that blogs didn’t receive more attention at the conference (though he hadn’t considered this until I pointed out their absence).

Concluding thoughts

Overall, Confab is an excellent conference. Other attendees compared it to conferences put on by A List Apart. I walked away with a lot of insights and ideas, and I have been very open in this post. In the coming weeks, I’ll try to post some notes from sessions I attended.

If this conference weren’t back to back with the STC Summit, I would recommend that more technical writers attend it. If you’re interested in learning more about content strategy, I recommend that you attend the Content Strategy Workshop that dovetails with Lavacon in the fall.

Blog Sponsors

Differences between blogs and wikis, and why you might need both

Tom Johnson — Thu, 19 Apr 2012 16:11:17 +0000

At work I have often grumbled about the fact that we have both a blog and a wiki, and that content shared between them sometimes seems redundant and unnecessary. However, I have since come to realize how well blogs and wikis fit together. I think it makes sense to have both — at least in my authoring scenario.

In short, wikis are suited for information that doesn’t expire in a short time, while blogs are better for short-lived news. The wiki is perfect as an ongoing encyclopedia of information that accrues in a larger and more useful, interconnected, comprehensive way. The information in a wiki is meant as standalone, long-term informative articles. You might expect to browse a wiki’s contents without regards to the dates each article was published. Of course there will be exceptions. All information has some time variable to it and will become dated — but not like information on a blog.

Blog posts are intended for more timely news. Although I cringe to write this, I know that as soon as blog posts slide off the homepage, they pretty much slide into the trash can. People are more likely to read old blog posts as they are likely to check out old newspapers from a library. Blog readers thrive on reading what’s new. They love to consume information that is of the moment, just published. Information that’s even a couple weeks old feels stale, as far as blogs go. Readers check out old blog posts only when they arrive at them through searches, if they are researching a topic.

Here’s an example of how blogs and wikis complement each other. Let’s say you have an upcoming release for a software application. You prepare informative release notes. Put the release notes on the wiki, since the release notes will be helpful to users for months to come (depending on the frequency of your releases). But since people don’t generally review the list of most recent changes to the wiki, you also post a note on your company blog about the new software update. The blog post is brief — just a summary or extract of the information contained in the wiki page.

Here’s a real example: LDS Maps release notes contains about a thousand words detailing what’s new in the application. But the blog post, LDS Maps version 3.0 released, contains only the first paragraph of the wiki article release notes, and a list of the new features. The blog post lets readers know there’s new information; the wiki provides the substance. Without the blog, you wouldn’t have a news mechanism for publicizing the information of the wiki. Without the wiki, you wouldn’t have a permanent source to store the product information.

Blog Sponsors

Guest Post: Why I Love Wikis

Tom Johnson — Sat, 14 Apr 2012 16:04:49 +0000

Neal Kaplan

The following is a guest post by Neal Kaplan, a technical writer at Zuora, Inc.

Another post about wikis? Why not! Wikis are great!

Just to set the stage, I’ve been a technical writer for a while now, working for software companies in Silicon Valley. (In fact, I often forget that there are technical writers who don’t document software.) I’ve worked at large companies, where I delivered my source files to a production team and then moved on to the next project, and as a team of one, where I was in charge of writing, producing, and delivering PDFs and online help to the end users. I consider myself an expert user of FrameMaker and RoboHelp.

And I’m happy to leave both of them behind.

Falling in love

Back in 2005, I had the opportunity to join a video game company (!!!) as a technical writer. I was in charge of documenting how to use game engine for an internal audience of game developers. They had a wiki with a small amount of information (written by programmers), which could be accessed from the game development application, so it served as online help.

This was a new world for me, and I loved it! No more lengthy production process (waiting for Frame to build books, then troubleshooting when it hung on a misplaced tag). Instead, I could publish the documentation as soon as I wrote it. When users found errors (it happens even to the best of us), I could fix them immediately, instead of having to file them away and wait to make them available with the next release of the product.

Better yet, I could ask the readers to help. I found that most people were more comfortable sending me a list of suggestions, but I did get a few people to help with tips and best practices. That information almost always comes from your advanced users, and it’s the information that they love to share.

But wikis aren’t exactly online help, and using them solely as a help system limits their usefulness. Even if many users don’t contribute, every user can contribute if they want to. They don’t need to own a copy of the authoring application, or climb the steep learning curve that comes with many of our tools.

Absence makes the heart grow fonder

When that job ended, I went back to a traditional Frame-to-PDF environment. And I couldn’t stand it. What user wants to read 1500-page PDFs? What writer wants to have to regenerate a book that big, with 20+ chapters, just to fix a typo on page 835?

And what happens to the PDFs? You write the content, generate the file, then check it in to be included with the software or post it on the company’s web site. And that’s when it falls into the abyss of the internet: Does anyone read it? How much do they read? Did they find it useful, or as a foolproof cure for insomnia?

Another opportunity to work with wiki-based documentation came my way, and I leapt at the chance. So far, I’ve merged two existing wikis into a shiny new wiki. I moved to a hosted system, using Mindtouch TCS, because it offers a clean, easy to use system with built-in templates, rating and commenting, and a straightforward way to build a documentation hierarchy.

While I was moving the existing content to a new wiki, I was pushed into a “social knowledge” project, where we bribed people across the company to document answers to frequently asked questions and best practices. I admit that I was wary at first: It’s one thing to have people make edits to your documentation (which you can easily review and fix, if necessary), but it’s a frightening new world for tech writers when anybody can write documentation! (Fortunately, wikis come with revision histories, and the ability to revert to a previous version. I’ve only had to use that once or twice.)

Of course, this is the whole point of wikis, and this project produced great content that would have taken me years to research and write. I found that while some people might object to criticisms about grammar and word choices, they were happy to help if I asked them to clarify an explanation or provide an example. I’m fortunate to be in a situation where my coworkers are one of my audiences, and they understand the need for good documentation.

A handful of employees continue to contribute documentation. Some people write lengthy topics, and some provide quick tips and best practices. All of this is hugely valuable to me, and to my readers. The next step is to encourage our customers to contribute to the documentation.

But on the other hand…

Obviously, I love working with wikis. But I will admit that they aren’t perfect and don’t solve every documentation problem.

Structure (IA and Content Strategy): One thing became clear to me soon after I started using a wiki to create documentation: A wiki is not a documentation set, and it’s not exactly online help. I realized that I needed to learn more about web structure, and that meant learning about information architecture and content strategy. IA is probably more directly relevant, but the concepts involved in both areas help me figure out how to design a structure that makes sense. Or at least identify when a structure doesn’t make sense. In fact, I’m in that position right now: my next big-picture task is to rebuild my doc site to have a more meaningful structure, instead of being mapped to our product’s UI.

Curation and Content Management: Without someone acting as curator, a wiki will very quickly collapse into a mass of unlinked, unstructured topics. Once you have built the structure, you need to keep track of what people are writing, and where. At a minimum, you will need to review new topics to add metadata.

For example, with Mindtouch I can add tags to topics, and they control what appears in the Related Topics area. This is hugely valuable, but it means that the tags need to exist, and that writers are consistent in their use of tags.

Single Sourcing: Wikis aren’t known for their single-sourcing functionality. Every wiki that I’ve worked with has a way to pull information from one topic into another, but it’s a manual process. This is manageable on a small scale, but I can see it becoming a problem once I have more writers working on more projects.

Here’s my shameful secret: I’ve been trying to avoid DITA. It just seems too complex for me to bother with, and I was there during the early, terrifying days of Frame-to-help conversion tools. I don’t need to reuse large amounts of content (so far), and I don’t want to get stuck writing dry, contextless snippets of information. I’m not writing massive guides for IBM servers, so why do I need the headache of DITA?

Obviously, that’s just the (mis)perceptions of someone who has only skirted the issue. I’ve talked to other writers about single-sourcing workarounds that they’ve implemented, but I haven’t come across an easy, automated solution to single sourcing to a wiki. Maybe I’ll have to give in and embrace DITA…but I shudder at the thought!

Ending on a positive note

I don’t think that those problems are insurmountable, or unique to wikis. All documentation needs a solid structure, after all. And there are huge advantages to being able to publish immediately and allow your readers to easily rate and comment on your documentation.

Many wikis also provide basic statistics about your documentation, such as a list of popular pages (based on page views and/or page ratings) and topic aging reports. It was easy for me to create lists of the most recently edited and the most popular topics and display that information on the front page.

Mindtouch TCS also provides information about search terms and results, which allows me to identify gaps in the documentation and improve the search results. For example, if users are searching for a term and not finding the correct topic, I can configure that search term to return the result that I want them to see.

Plus, it includes the ability to save topics to PDF. Any reader can save a single topic, or a topic and all of its child topics. It’s easy to create a PDF containing every topic in the Knowledge Center (and a few people have asked for that functionality). Of course, I update the documentation daily, so those files are almost instantly out of date. But that’s a limitation with any static document.

I’m also using Google Analytics with my documentation site, which gives me an enormous amount of information. Besides getting more information about the number of people visiting the site, I can track how users are navigating through the documentation, which browsers they’re using, what screen resolutions they’re using, their language settings…basically, information that helps me determine what I need to support, and what I can do to make the documentation better for my users.

I’ve just hired a second writer. I’m excited to be working with another tech writer, and I’m looking forward to launching a new doc structure, getting more systematic about adding links and tags, and finally getting serious about adding videos to the site.

Neal Kaplan is a principal technical writer at Zuora, Inc., in charge of the Zuora Knowledge Center (http://knowledgecenter.zuora.com). Five of his 17 years as a technical writer have been spent working with wikis. Even after 17 years, he feels that there’s still a lot to learn about writing great documentation. Neal lives in the San Francisco Bay Area with his wife and two daughters, and can be contacted at nealbkaplan@gmail.com.

Blog Sponsors

Subpage Titles on Wikis — Challenges, Conventions, and Compromises

Tom Johnson — Thu, 22 Mar 2012 13:58:30 +0000

One of the challenges with wikis (or at least with Mediawiki) is figuring out how to title pages that all belong to the same product or group. I spent a bit of time researching best practices with this and didn’t come up with a clear answer. I tried to also figure out why I’d never come across this page titling conundrum before.

Here’s the problem. On a large wiki, you have pages about many different products. For simplicity sake, let’s say that on your wiki, you have documentation about products A, B, C, D, and E. Instruction for each of these products is rather long, so rather than having each wiki page contain all the information for the product, you decide to break up the information into smaller pages. After all, you are conscious of people saying TLDR (“too long, didn’t read”) and simply dismissing your content. So let’s say you break up each product’s instructional content into 10 pages each.

For product A, some of these topics include titles like Setting preferences, Running reports, Creating widgets, and Adding new users. For product B, you have similar but slightly different topics: Configuring your profile, Exporting reports, Adding widgets, and Setting up new users. The other products have similar topics.

If each product’s topics were kept in separate, clearly distinct containers, you wouldn’t have much of an issue. And in fact traditional webhelp files do usually segment product information like this. In a traditional help authoring scenario, each product would have its own generated webhelp output, and it wouldn’t matter if the topic names were similar because the content would be siloed from each other anyway.

However, wikis are different beasts. Usually an organization’s wiki acts as one platform for many products. Help material for products A, B, C, D, and E are all on the same wiki platform. As such, there’s a need to distinguish product help from each other through unique page titles.

Wikipedia has several techniques for doing this. At the category level, one technique is to name each category with your base category name, and then add the subcategories in parentheses after the base name. You have to see this in action to really grasp it. Check out their Manual of Style. This Manual of Style is rather large. If editors put it all on one page, you could probably scroll down for hours before you reached the end. So they divide this content into various categories. Categories are like chapters. There’s a category about formatting, images, layout, and more. (See all categories.)

When a topic has multiple categories, the categories appear in parentheses after the topic name.

Rather than just listing category titles as “Formatting,” they write “Manual of Style (formatting).” In other words, they include the product name first, and then put the category name in parentheses following the product name. Presumably this is because readers need to know that the category fits within the Manual of Style and is not just about formatting in general.

When you click the Formatting category, Wikipedia implements another technique: the slash. The Manual of Style (formatting) category has pages in it with names like “Manual of Style/Dates and numbers,” “Manual of Style/Capital letters,” “Manual of Style/Proper names.” “Manual of Style” is the base page name, and the title after the slash is a subpage for that page.

Subpages have a slash in the title.

If this weren’t enough, Wikipedia also incorporates a namespace for this specific category. The actual title of these pages is “Wikipedia:Manual of Style/Proper names.” The namespace puts the page into a specific space that segments the content differently in searches. Content in the Wikipedia namespace discusses the Wikipedia wiki itself.

The slash is a fairly common convention on wikis for denoting subpages. WordPress’s wiki uses slashes in titles for their Function Reference subpages.

Subpage conventions with WordPress' Codex

Interestingly, this appears to be one of the few examples of subpages on the WordPress Codex wiki. Their style guide cautions against subpages as follows:

Do not create sub-pages of a page, other than from your own User page, without discussing first on the wp-docs mailing list. Exceptions to this are the pages under Function Reference (each of which describes a single function).

Undoubtedly, neither the parentheses nor the slash provide elegant ways of titling pages. Imagine titling every one of your help pages with the product name first, followed by a slash with the real page name. At the same time, imagine not including the base page in the page’s title. The function references shown above would be a mess!

The subpage name technique is ugly for at least two reasons. First, it’s ungrammatical. Traditionally, the slash denotes an either/or significance, so writing Manual of Style/Proper Names literally means that you could refer to the content either as a Manual of Style or Proper names; the two words are both interchangeable or applicable. This is not really the case, though.

Parentheses aren’t much better. “Manual of Style (Proper names)” suggests that Proper names might be an alternative name for Manual of Style. Parentheses traditionally indicate a whisper or an aside comment.

Only those familiar with Wikipedia’s conventions, or who guess the meaning of the conventions based on the context of the titles they’re seeing, will understand the real meaning of the slash or parentheses.

Despite the unconventionality of titling pages this way, slashes seems to be the convention on wikis for denoting subpages. Here’s how Mozilla’s wiki uses subpages:

Subpages on Mozilla

Not all wikis use subpages. The Embarcadero wiki doesn’t seem to use them. If they need subpages, they put the subpage name in parentheses.

Subpages on the Embarcadero wiki

The Knoppix wiki just seems to use subpages for things like bugs.

Subpages on Knoppix

Other options for article titles are also problematic. Some people recommend that you start the page name with the product title. With this method, you end up with titles such as Acme Configuring your profile, Acme Exporting reports, Acme Adding widgets, and so on (assuming your product’s name is “Acme”). Sometimes this works. Many times it doesn’t.

An alternative might be to integrate the product title somewhere in the article title. For example, Configuring your Acme profile, Exporting reports from Acme, Adding widgets to Acme, etc. This is all right, but what happens when the product name doesn’t fit into the title? What if the product name is long and unwieldy, or a clunky acronym? What if your product name is Linguistic Analysis Algorithm Identifier, or something horrendous?

Another approach is to leave out the product name from the title altogether. If you have a sidebar with the collection name, that sidebar will provide some context about the product. This allows you to use graceful looking titles, but this method falls short when the sidebar isn’t included with the appearance of the page title. Search results, category lists, recent updates, page lists, and other areas of the wiki will not include the contextual sidebar.

I’m somewhat baffled by this page titling conundrum. I’m leaning towards the slash method only for content that has a clear top page, as pointed out in this heated discussion thread. In general, I would like to omit subpages in titles altogether. In this same thread, one person notes that subpages are usually unnecessary because articles should stand by themselves:

Aside from arguments based on technical or usability details (subpages do not have breadcrumbs in the main article space, newbies would find them confusing), we don’t use subpages in the main namespace because they should instead be valid articles in and of themselves. This is the practice; for example History of Canada is effectively a subpage of Canada, but is valid as an article in its own right. Indeed, it’s a guideline that Good and Featured articles must follow to some extent: Wikipedia:Summary style. Nihiltres^{t.l} 19:01, 20 April 2008 (UTC) (See thread.)

This is perhaps why articles on Wikipedia are so long. What do you recommend in this situation?

Blog Sponsors

Guest Post: Wikis Are the Future of Technical Documentation

Tom Johnson — Tue, 20 Mar 2012 14:56:10 +0000

Mick Davidson

The following is a guest post by Mick Davidson, a technical writer with 20 years of professional writing experience.

Before I get started I’d like to thank Tom for giving me this opportunity to bang on about why I think wikis are the future for technical documentation.

Like many writers, up to a few years ago I was plodding around using backwoods technology, stuck with systems that had once been great but now begged to be retired. From a personal angle, I felt I was stuck with dull tools, tools that were not joined up, couldn’t talk to each other, and excited me not one jot.

Then in through the window came the wiki — and everything changed. Now, three years on and two wikis later, I am 100% convinced they are going to be one of biggest and best documentation tools we have. In short: revolutionary.

There are perhaps four reasons for this:

They are simple to use.
They are very flexible.
They expand as your content grows.
They make life as a technical author an absolute joy.

The latter is particularly important for me as I do not go to work to trudge through thousands of words with something as dull as a word processing package. I don’t want to use a system that hedges me in: I want more. I want a technology that gives me what I need and a lot more besides. And I want excitement!

There is at least one wiki system that offers all this. This system is called Confluence, by Atlassian, an Australian company that has, in less than ten years, come from nowhere to being a major player with 18,000 clients worldwide including Adobe, Twitter and Facebook. This is enterprise with a capital E. But don’t just take my word for it, see for yourself at www.atlassian.com.

There are many other wikis out there, and I’m sure many of them are very good, though I’m not sure they are all enterprise level. Small can be beautiful, but corporations want technology that punches at the same weight as they do — or higher, and because they want to feel safe. MS Office is everywhere because it delivers the goods for many businesses. However, MS Office does not and cannot do what I felt we needed. And nor did any other system I investigated, all of which were far too rigid and expensive.

What we needed was a flexible, extensible system with built-in macros that enabled us to extend what we once called documentation into what is now known as content. Content can be words and graphics, as well as slideshows, audio and video etc.

The system also had to allow us to build and expand the structure as we needed to, easily and without fuss. As a lone author, I don’t want to spend my time building pages and structure — I want to spend it on content that is, for users, as interesting and rewarding to read and experience as it is for me to create.

So, apart from all that, what does working with a wiki offer technical writers? How does it let us do our job better? Why is it more fun?

For a start, the wiki offers simplicity in every direction. In Confluence, and this may not be true of all wikis, it’s ridiculously easy to create a set of pages that are linked to each other and to pages elsewhere. Structures form of their own volition as your content expands. Styles and formatting, which are already set up but can be changed by editing the CSS, are enforced throughout all pages, even when you import a Word document. Sure, you can’t stop people adding their own styles, but you can’t in Word either. And, as technical authors, we obviously don’t need to be told to stick to our in-house styles, so using what’s there isn’t a problem.

Two of the biggest advantages are searching and linking. For me, these two things are possibly the most crucial elements. If there was one thing clients used complained about, it was the limited search capabilities offered by more traditional documentation. Before the wiki we had something like 70 user guides, how-to guides, white papers, and various other documents. If you wanted to find something you had to go through each document, one by one — which is a tedious and often frustrating process, especially if you’re looking for topics that might be in more than one guide. A wiki can be viewed as a database of information that lies behind a very attractive front end — all of which is searchable at the same time.

With a wiki, everything is connected. Run a top level search and you search all your user information — in a second! And if you get too many results, you can simply modify or refine your search to focus it onto content sub-sets, by using labels (or tags as they are also known). In Confluence you can also search by date, the page’s author, and content type. For example, you can search the graphics as well as page names and words. In the end, both you and your clients benefit from this functionality.

And yes, I know you can achieve quite complex searches in other systems, but in my experience, you cannot create them as easily and quickly as you can in a wiki.

Wikis also offer advantages with linking. Links not only provide an alternate way of navigating, they take you to related content, wherever it is, so you can surf pages in the same way you’d surf content in any other website. The fact that you can link to specific topics directly from your software (surrogate help?) is brilliant for lone authors and those with limited budgets and time.

And these are just a couple of the benefits. We haven’t begun to explore collaboration. We’re now getting developers to write user content of their own free will, and clients help us improve documentation by adding comments.

Did I tell you that I’ve just started setting up a user forum in our wiki? Yes, me, the technical author, not a programmer or a web developer. With the wiki this opportunity is in my hands.

Then there’s the ridiculously cheap price. Well, in Atlassian’s case anyway. I doubt that you’ll find anything that offers so excellent value for money as a Confluence wiki. Ok, maybe you will if you’re looking at their other products such as JIRA.

For the last 12 months I’ve been writing all our user information in our Confluence wiki. Before that I used another enterprise-level wiki for two years. Enough time, I think, to get a very good picture of what wikis can do and understand what their potential is. And I strongly believe they are the future. So much so, that nowadays I’m only really interested in working for businesses that use them. Anything less would be, well, less.

But don’t take my word for it. Find a wiki that seems suit your needs, download a trial version and see how you get on. I doubt very much that you’ll regret it.

Mick Davidson has been a professional writer for 20 years as a journalist and technical author. He works mainly in the software industry and attended Atlassian’s recent Unite conference in London, where he took nine pages of notes. He can be contacted via at mjmdavidson@gmail.com. You can follow his blog at http://davidsonmedia.weebly.com/techno-blog.html.

Blog Sponsors

Why don’t technical writers use wikis — or do they?

Tom Johnson — Fri, 24 Feb 2012 07:26:50 +0000

The following is a guest post by Sarah Maddox, a technical writer at Atlassian.

Sarah Maddox

In a recent conversation, Tom mentioned that he’s been pondering this question: “Why, in a time when collaboration is more important than ever, do wikis still remain mostly unused as a help authoring tool in tech comm departments?” Tom asked me to join his ponderings and write a guest post on the topic. Thanks for the invitation and the thought-provoking question, Tom!

I started by thinking about the question itself. Do we know how many people use wikis as a help authoring tool, and what do we mean by help? For this post, let’s say that “help” means technical documentation in general, which I think is the thrust of Tom’s question.

Is it true to say technical writers don’t use wikis?

Serendipitously, two bits of news appeared just as I was about to put my ponderings to paper.

The first was a guest post by David Kowalsky on The Content Wrangler: Collaborative Authoring and Communication Tools Help Writers, Editors, SMEs Work Together. The post discusses a number of collaboration tools, yet wikis get only a very brief mention: “Wikis are becoming more widespread.” That’s it.

So, that post lends strength to the surmise behind Tom’s question. Wikis are only barely in the picture.

Then another bit of news popped up – the results of the 2012 WritersUA Skills and Technologies Survey. When conducting the survey, WritersUA provided a list of popular user assistance technologies and asked the respondents to value the importance of those technologies in their current development efforts. The technologies section of the survey shows that 28% of respondents rate wikis very highly.

28% is not to be sneezed at.

One respondent noted:

Ask again next year and the landscape will have changed dramatically. We intend to migrate from Webhelp to a wiki/kb delivery model and I can’t wait!

WritersUA also provide details of specific tools, where wikis are mentioned quite a bit too. Try searching the page for “wiki” and “confluence” (because the latter is mentioned without the word “wiki”).

Rephrasing the question asked in this post

Based on the WritersUA results, I’ve changed the question slightly. Instead of asking why wikis remain mostly unused as a help authoring tool, let’s ask, “Why don’t more of us use wikis as a help-authoring tool?” It’s an excellent question to address in a blog post. There are likely to be some passionately-held opinions and some great stories around the use of wikis, experimentation with wikis, trials and tribulations as well as thrills and conquests. Bring ‘em on, folks.

So, why don’t more of us use wikis as a help-authoring tool?

I think the crux of it is this: each type of tool makes one set of functionality easy, and supplies other sets of functionality via add-ons or processes that are less comfortable.

Wikis excel at collaboration, notifications and monitoring of updates, integration with other web apps, sharing content, and social features like networks of colleagues and status updates. They also provide instant gratification, by publishing updates as soon as you click save. (That’s the default behaviour, though in some wikis you can configure a workflow to delay publication.) Wikis are great at publishing good-looking documentation with a minimum of fuss and bother.

Wikis are not so good at version control across a documentation suite, single source publishing, or topic-based authoring. They were not originally designed with that focus in mind. But there are add-ons currently available that extend the wiki functionality in the directions we need, and there are more add-ons under development that will do it even better.

Dedicated authoring tools excel at single-source publishing. The newer tools focus on structured authoring. Many of them either have their own version control system or integrate with the same source control tools used to store code. On the other hand, such tools are designed for use by a small, dedicated team. They tend to lock out people who are outside the technical writing team, due to license costs and/or technical complexity. Collaboration is therefore difficult. There is a publishing step between updating the content and making it visible to readers, which may require a delay of some hours until the documentation can be built. Some tools have introduced social features such as commenting, but the published documentation suite does not offer the people-focused experience that a wiki offers.

Can you have all the features in one tool? That would be great, and the need is there. I don’t know of a tool that elegantly satisfies all requirements. Not yet. But there are some promising developments underway. Because I’m so deeply involved in the world of wikis, I know of the excellent plugins and add-ons under development to add workflow, single sourcing and sophisticated version-control to a wiki. I’m sure that people reading this post know of the new collaborative and social features being introduced into other tools.

Weighing up priorities

Technical communication is a broad and diverse field. There are as many ways of categorising what we do as there are environments that we work in. Not surprisingly, there are as many ways of prioritising our needs too. It’s up to us to choose the tool that fits our requirements. Each tech comm team has to weigh up the priorities, based on the aims of our organisation, team and audience.

But here’s the thing: We can help by knowing the capabilities of each tool, and educating our organisations about the benefits of each.

It can be hard to know the capabilities and functionality of a wiki, and especially the capabilities that are useful to technical communicators. Wikis are constantly evolving. Sometimes additional functionality is available via installing a plugin, but it’s difficult to find that information. Or perhaps the features are there in the wiki, but are not packaged and labelled as something useful for technical documentation. For example, wiki documentation may talk about spaces, watches, notifications, RSS feeds. We need someone who is already in the know, to describe the features and show us how to use them in our workflow.

Maybe those of us who use wikis are just not especially vocal about it. Here’s a suggestion: Wiki huggers need to jump up and shout it out: Kiss my wiki.

A lot of it comes down to communication and help.

Difficulty harnessing the power of the crowd

Collaboration is a consummation devoutly to be wished. (OK, maybe not for all documentation suites, but let’s assume that we want collaborative authoring now since that’s the topic of this post.) But it’s not easy. Collaboration can be a messy business. This may be one reason why technical communication teams have not yet implemented a wiki-based solution. They’re looking for success stories. Has anyone successfully opened up the product documentation to updates by external authors? How about letting everyone in the company update the docs, or even company partners and community developers. How about the general public?

This is a broad topic. For my team, I can say that we are making it work, that it’s fun and challenging and rewarding, and that we constantly re-evaluate the way we do things to see if there may be a better way. Our documentation is continuously being updated by subject matter experts (developers, support engineers, marketing engineers, product managers and even a CEO or two). We also have a group of around 50 community authors who update pages every now and then, particularly in the developer-focused documentation.

This post would become very long if I included guidelines on how to manage the updates by everyone. Instead, here are some pointers about the things to consider:

Permissions: The tool you choose must allow you to define groups of people (technical writers, company staff members, community authors, etc) and to assign permissions to each group.
Monitoring and notifications: You must be able to subscribe to an area of the documentation, and receive notifications whenever someone updates a page.
Copyright and intellectual property: You will need to display a suitable copyright license (we use Creative Commons by Attribution) on all the pages, so that contributors and readers alike know their rights. It’s also a good idea to ask contributors to sign an agreement, signifying that they understand the intellectual property arrangements for the content that they contribute. Our agreement is based on the Apache Contributor License Agreement.
Encouraging people to contribute: It’s safe to say that you won’t be deluged with updates. Instead, invite people to update the documentation and keep telling them how much you appreciate their contributions. The experience is rewarding and enlightening. Every day you’ll learn new things about your readers and the way they use your products.
Style guides, templates and structure: It’s a bit of a balancing act. Too much structure can deter contributors. Yet everyone appreciates some guidelines. Templates are very useful, especially in getting rid of that dreaded empty page that needs filling. A light style guide, informative rather than prescriptive, is useful to external as well as internal authors.

The above points are some of the things to consider when allowing other people to update the documentation pages. There’s more to think about when you allow people to add comments to the pages. For example, the volume of contributions in comments can be overwhelming – people are more likely to add comments than to update a page. You’ll need to ensure that management understands the number of people required to handle such input, and the different types of comments that you will receive. In our experience, most comments are calls for help rather than points about the documentation itself. It’s therefore useful if the support team and developers can help respond to the comments too.

The most rewarding thing of all is that people help each other. Someone asks a question, someone else answers, and everyone benefits, without the technical writers needing to intervene at all.

Customisable look and feel

Technical communication teams need to add a brand to the documentation (logos, colours, fonts). They may want a tripane help system or something that looks closer to a website.

In the early days, all wiki documentation looked the same. Bland, black and white with blue links, and if you were lucky a left-hand navigation bar with a table of contents. Above all, there were no rounded corners to be had for love nor money.

Things have moved on, and wikis allow a fair bit of customisation via themes (skins), CSS, replaceable logos, and more. But I think many people still hark back to that era of prosaic look and feel when they hear the word wiki. Here are some wiki sites with a sophisticated look:

splunk>docs
Atlassian developers
PNI
WoWWiki
Any more? If you know of other pretty wiki sites, please add a link in a comment.

What’s in a name?

A couple of times I’ve heard people say that the name “wiki” puts them off. The word sounds trivial, not suited to the powerful tool they’re looking for. It doesn’t reflect the multifunctional tools that wikis have become. Other people say that “wiki” sounds old and dry – very 90s.

Some wikis have changed their description to “collaboration platform” or something similar. MindTouch, for example, is based on DekiWiki. At the moment, the MindTouch website calls its platform the “Social Help Center with Knowledgebase and Help System”. (Note that David Kowalsky does mention MindTouch TCS in his post on The Content Wrangler.) At Atlassian, there are mutterings every now and then about what to call Confluence. Should the word “wiki” appear on the website, we ask ourselves earnestly? The product page title currently says “Content and Social Collaboration Software”.

My 2c? I like the name “wiki”. It’s simple and cute. It retains the history going back to the very first wiki, invented by Ward Cunningham and opened to the world in 1995: WikiWikiWeb, also known as just plain Wiki.

And you know what? “Wiki hugger” sounds so much better than “collaboration platform hugger”!

Honk, beep and wave

So, honk if you’re using a wiki for technical communication. Beep if you’re considering it. Wave if you’re not. I’d love to hear what everyone thinks about the points in this post. And tell me what I’ve missed!

About Sarah

Sarah is a technical writer at Atlassian, makers of Confluence wiki and other software tools. She has 14 years of technical writing experience, the last four of them on a wiki. Sarah’s new book is about developing documentation on a wiki: Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. It’s also about technical communicators. And chocolate. The book covers the points mentioned in this blog post, and a lot more. The book is published by XML Press, and is available on Amazon.com and Barnes & Noble. Sarah’s blog is at http://ffeathers.wordpress.com.

Blog Sponsors

What I Learned About Tech Comm During 2011

Tom Johnson — Wed, 28 Dec 2011 15:31:48 +0000

This past year I learned a few things. As I approach 2012, I’d like to note what 2011 taught me:

Writing documentation in a wiki suits me for the same reasons I enjoy interacting on the web. The web is interactive, alive, dynamic, collaborative, fresh, and unlimited in potential. A wiki, being online, allows me to partake in the same game-like, community-rich environment that I thrive in.
It’s much better to focus on just a few key projects rather than spread myself too thin. I made the mistake of extending my reach into too many projects this year, sometimes taking them upon myself because the applications needed help. As a result, I wasn’t as informed as I usually am about the most important projects, and it showed. Later I pulled back and ignored everything but my two main projects, and I felt much better with this strategy.
I need to set goals to write at work. It’s astonishing how non-writing tasks can eat up the day. Lately I’ve set a goal to write for 4 hours a day at work. I rarely achieve this, though really this goal has caused me to reflect on what writing actually is. If I’m reviewing forum threads to detect issues to write about, or experimenting with a test system to determine steps for documenting a task, isn’t that writing? The typing part comes at the end and is fairly minimal. Regardless, just setting a timer on my iPhone prompts me to dig into the documentation topics and produce something tangible.
Content marketing, played out in the form of corporate blogging, is kind of boring. Corporate blogging isn’t what I thought it would be. Mostly the corporate scenario is stifled by lack of creativity and freedom to explore. You’re expected to toe the line, to avoid controversy, to vet each post through five levels of approval. Comments from readers are usually brief, unenlightening, and often don’t match the topic of the post. I find technical writing more engaging.
A centralized help authoring system is a neat idea, but I hate the lack of control. The idea with a centralized help authoring system is that you install the system on a server with all your styles defined in one central location; an administrator sets up everything to be a push-button publishing solution, and then everyone else just “focuses on content.” However, when you’re used to designing your own help solution, learning to rely on one (often remote) person is discomforting. I like having some control over the design, layout, style, and publication of my help material.
Community collaboration is extremely tough to pull off. I can’t just assign a volunteer writer a topic and let them run with it. I usually have to either gather the information from a subject matter expert or connect the volunteer with a subject matter expert — and then see them through the process with more hand-holding than I want to provide. Still, community volunteers can generate momentum by the sheer number of assignments I have to follow through with. Overall, I have no idea how to engage community volunteers in an effective way, but I think I can eventually figure a strategy out.
Sitting embedded with my project team is more effective than sitting with other technical writers. Sitting with my technical writing team, I end up collaborating a lot on standards, goals, styles, and other issues — which can be useful and important. However, the core substance a technical writer relies on is project-related information. No matter how many IRC meetings, scrums, iteration reviews, and other interactions, nothing replaces the information and rapport you get through proximity to the project team. However, proximity to the project team is just one element. Proximity to end-users is even more important. (See my post on The Proximity Problem for more analysis.)
Just because my job involves sitting at a desk all day with little movement, it doesn’t mean I’m fated to become a couch potato. By counting calories and following a whole-foods, mostly plant/fruit/grain diet, I can actually lose weight while improving my overall health. I’m not becoming a vegan or anything, but I had no idea how poor my eating habits were. The My Fitness Pal iPhone app gave me a wakeup call. The Forks Over Knives documentary on Netflix also made me question the integrity of the traditional food pyramid.
I’m not that interested in fiction. In the fall, I went through a fiction phase that lasted a good three months. During that time, I read and wrote more fiction than I have for the past 10 years. I eventually lost interest and realized I was more attracted to non-fiction for reasons I can’t entirely explain. I like the immersion in ideas (not that fiction is idea-less, but the ideas are shown rather than explained). I enjoy the sense of being “on top of the game” when I’m immersed in non-fiction (such as findability topics) and blogging about these same ideas. It infuses me with a lot of enthusiasm for my job, this blog, and my overall career.
Metadata is the most compelling strategy for findability, but I don’t know how to harness it yet. I experimented with the Semantic Mediawiki extension in a help system, and I liked the ability to tag and query topics in new ways, but I didn’t explore this strategy enough to be successful with it. I feel that I’ve only scratched the surface. There is so much more to discover. David Weinberger’s book Everything Is Miscellaneous, which explores metadata in depth, was the best book I read in 2011.

Based on what I’ve learned, as I go into 2012, I plan to do the following:

Use Mediawiki more.
Set goals to write more at work.
Focus on fewer projects.
Possibly hire an intern to help with the corporate blog.
Leverage community volunteers for non-writing tasks.
Eat smarter.
Read more non-fiction books.
Figure out metadata and findability.

Note: I do change my mind frequently, so no doubt this list will evolve as the months in 2012 pass by.

Blog Sponsors

Wiki Culture, Reader/Writer Distinctions, and Divergence from Structured Authoring

Tom Johnson — Sat, 19 Nov 2011 21:37:06 +0000

In my last post on wikis, Mark Baker added an astute comment:

I’m not a wiki fan myself — I’m a structured text guy bred in the bone — but I am fascinated by the trend, and by the variety reactions to it.

Wikis started more as a cultural statement than a technology. They were a tool for the democratization of content, the intent being to eliminate the distinction between reader and writer. In the wiki philosophy, every reader was also a writer, there was no ownership of content, and not notion of a final, finished, of blessed editions of content. The wiki was always open, always evolving, and blessed only by the consensus of the community. Today, it would style itself “occupy content”.

What wikis have become, largely, is an unstructured CMS with only one face. A traditional CMS has two faces: one toward the author, and one toward the reader. A wiki has only one: the same face toward reader and writer, with every page having an edit button on it. Except that today the edit button is locked or hidden from most users. The distinction between reader and writer has been reintroduced and enforced. The original wiki philosophy has been rejected.

Still, the stated motive of most people who adopt wikis for technical communication is to allow more collaboration and to open up authoring to a wider community. So some shadow of the wiki philosophy is still at work. That being the case, I think there are a couple of things that people need to understand about the wiki philosophy and its consequences.

The first is, if you want to crowdsource effectively, you need to be open. People need gratification. If the content they contribute disappears into a black hole of moderation and curation, they don’t get the immediate gratification of seeing their work published, and gratification delayed is gratification denied. You won’t get a lot of content from the crowd unless you let the crowd publish.

The second is a consequence of the first. The implication of the idea that there is no distinction between reader and writer is that the reader has to take more responsibility for what they read. The old contract between the writer and reader of technical content, that the published content had been vetted and could be relied upon uncritically, cannot be sustained in a crowd-sourced world. The reader of a wiki, like the reader of any Internet content, has to assume some responsibility for vetting the content they receive.

By and large, readers do understand this. It is the responsibility they accept every time they type something in a Google search box. The simple fact of the matter is that readers prefer unblessed content that addresses their task and is available now over blessed content that does not cover their task or will not be available until next year. Timeliness and coverage trump all other considerations most (thought definitely not all) of the time.

The question for tech writers is, is there a place in your hearts, and in your company’s relationship with its customers, for unblessed content that enhances coverage and timeliness?

I like Mark’s comment for several reasons. He brings up several key points with wikis:

“[Wikis] eliminate the distinction between reader and writer.”
“Readers prefer unblessed content that addresses their task and is available now over blessed content that does not cover their task or will not be available until next year.”
“People need gratification. If the content they contribute disappears into a black hole of moderation and curation, they don’t get the immediate gratification of seeing their work published.”
“The old contract between the writer and reader of technical content, that the published content had been vetted and could be relied upon uncritically, cannot be sustained in a crowd-sourced world.”

When we talk about wikis, it’s important to see them as more than just another authoring platform. As a reader, knowing that I can change the text alters my sense of the text. It is no longer the absolute word on the matter. I can be a part of the conversation; I can change the message. It is my content as much as another’s.

And making those changes immediately, seeing it published instantly, is gratifying. It’s empowering, almost to the level that the printing press changed the distribution of knowledge. Wikis take it to another level, allowing every reader to also be a publisher. Tapping into the knowledge that every reader has, inviting the reader to share that knowledge, and trusting the reader that he or she will shape the content responsibly, isn’t just a shift to another tool. It’s an entirely different way of thinking and interacting. It’s the 21st century interactive read/write web model. It’s a model that acknowledges that the sponsoring organization doesn’t have all the knowledge, but that individuals located in disparate regions also have important contributions to make — and that they should share those contributions. Wikis democratize the knowledge landscape, allowing everyone to speak without pre-filtering editorial control.

This is why, like Mark, I am also fascinated by wikis. In an organization like mine that is traditionally top-down, with careful filters on outgoing messages, a wiki is a complete anomaly. And yet, it is also not an anomaly. Latter-day saints have a history of volunteering, of consecrating their efforts for the community. In the nineteenth century, members would contribute their time, talents, and own funds to build temples (which took years), or to work in fields. In this sense, a wiki is a perfect fit. It is a knowledge project rather than a physical structure project.

Mark also brought up the fact that he is a “structured text guy bred in the bone.” I was talking with Scott Abel last week, and as Scott was explaining something about structured authoring, I brought up this question: Don’t you see wikis and social media as going in the opposite direction of structured authoring?

I know we need to put our content into structured forms so that it can be leveraged into other channels we need to publish to (ePub, mobile, web, print, and more). But it’s impractical to ask people in the community — who are not technical writers and who do not have your same toolset and knowledge — to write in structured formats. Taking contributions from the masses requires you to simplify your authoring model. You end up with an either/or choice. Either you can go the structured authoring route, or you can go the social collaboration route.

In response, Scott mentioned a point similar to what Mark says about content management systems. The only thing that really separates a wiki from a content management system is that the content management system hides the Edit button from the user. If I were to give you login information for my WordPress blog, for example, you would see an Edit link below the post title. You could log in and make changes to what I’m typing right now. With one flip of the switch, I could simply convert this WordPress content management system into a wiki-like platform, breaking down the division between reader and writer, and accomplishing the same end. Right?

What’s more, if the content management system stores content in XML, or relies on some other structured authoring interface for writing content (you can export from WordPress to DITA, for example), it would solve the problem that I describe above about the divergence of structured authoring and social media. Right?

Sort of. I would like to see more content management systems move in this direction. I’m not that familiar with all the various content management systems out there and the number of wiki-like interfaces they potentially offer. In my experience, many times the content management system is behind a firewall or has other security restrictions. Many content management systems may not provide the inviting simplicity that traditional wikis offer. And licensing is also another issue. As a result, more often than not, users cannot simply click an Edit link and start updating content. However, I think that it’s only a matter of time before this becomes more normal.

What do you think? Do you agree with Mark’s observations about wikis? Are socially collaborative tools and structured authoring going in different directions?

Blog Sponsors

Why I Returned to Wikis for Help Authoring

Tom Johnson — Tue, 15 Nov 2011 03:39:28 +0000

Last week I was feeling a bit stretched out about not having enough time to accomplish everything I needed to do. Granted, I gave several webinars to a total of 2,000 people, which was somewhat stressful, but I was more stressed about the fact that the help material I’d created could have been much better if I had only more time to focus on it. And it wasn’t just help for one product, but about ten others as well, simply because I didn’t have the time to provide the detail and attention the documentation needs.

It’s not because I’m lazy. I’ve actually become somewhat of a workaholic, working on weekends, sometimes a little in the evenings. The problem is that there simply aren’t enough technical writing resources for the work we do.

This situation was taxing my patience, and I started to think of the immediate solution: hire more people. I already mentioned that we have one opening. This is just back-filling a position from a writer who left. But we need about half a dozen more writers, in my opinion, to do a good job. I thought about trying to hire interns, or trying to recruit full-time volunteers.

While I thought of these staffing solutions, I also thought of other things I have heard our leaders say. We have to find a way to meet the demands of a growing membership without commensurately staffing up, some said. And another: If you set your goals higher than you can achieve, you will change your methods in a way that allows you to achieve them.

While I liked these ideas, I didn’t have a clear idea of how to move toward them. I was constantly working in crisis mode, trying to cross off the top three items from an ever-growing list of tasks each day.

As if the documentation challenges weren’t enough, I had also taken it upon myself to do marketing for technology products across departments. I fished for tech news information in every corner I could find– forums, RSS feeds, intranet content, email lists — and then worked with volunteer writers and subject matter experts to get the articles written. I greased the approval system, learning how to navigate the large number of checkpoints with skill and prowess.

Despite some successes, I realized I couldn’t move in two directions at once, both playing documentation and marketing roles for so many products. I needed a way to scale without simply growing our team with more full-time resources.

A Glimpse of the Solution

Just last week, I felt like I caught a glimpse of the solution. I have a group of 60+ volunteer writers eager to help out. (I wrote about the challenges of managing volunteers last week.) In fact, there are hundreds of church members (as well as non-members) out there who are eager to serve and volunteer for LDS Church writing projects (I work for the LDS Church). I hadn’t leveraged their efforts except for the marketing side of tech, writing articles for the blog about new releases, updates, and other technology topics. I didn’t have them creating documentation because I saw these as separate efforts.

And then it hit me: These aren’t separate efforts. Good documentation about new sites, tools, and resources can be used for marketing efforts. Marketing and documentation don’t need to be separate efforts. I could leverage volunteer enthusiasm for documentation and then pull highlights from the documentation to post as news for the blog.

And what platform would allow 60+ volunteers to contribute writing and editing? The traditional help authoring system we were using didn’t seem adequate. The cost per license and lack of availability outside the firewall made it impractical as a collaborative volunteer platform. About the only platform that works in this situation is a wiki.

One of my colleagues explained that volunteers could write in Word templates and then send me those templates. I could then import the templates into the help authoring system and generate help material from it. This was a system he had used in the past for internal SMEs who wrote content. While this could work, he acknowledged that the process would be somewhat impractical.

One of the problems is that we don’t have a set of number of official products we document. If you look at this list of categories on LDSTech, our users have questions that span across products, departments, and roles. There are dozens of different topics, sites, tools, resources, applications, processes, methods, issues, and other areas that users have technical questions about. Would I create a new project to publish information about each one? The most feasible platform to accommodate such an information ecosystem is a wiki.

Pros and Cons of Wikis

I have to say that, in general, I really like wikis, especially Mediawiki. Wikis have so many advantages that it’s hard for me to understand the case for traditional help authoring systems when you need a collaborative authoring environment. Here are the main advantages I see with wikis in my authoring situation:

Wikis scale infinitely. Mediawiki is actually free, and it supports an infinite number of users. You don’t have to shell out $1,500 per license. People can just log in and start authoring. It scales to support a growing user base.
Wikis remove authoring complexity. Some help authoring tools require a lot of tinkering before they make sense to users. In contrast, adding content to a wiki is fairly straightforward. It’s a matter of asterisks and pound signs and equal signs, for the most part. There is some syntax to learn, but it’s nothing prohibitive. This is essential to expand the base of authors.
Wikis allow collaborative authoring. When you have multiple people working on the same content, nothing is easier than a wiki to facilitate this collaboration. Mediawiki even allows more than one person to work on the same page at once, and is smart enough to handle simultaneous commits of the same sections.

I mentioned that I’ve tried using wikis before. Some of the reasons I abandoned it previously include the following:

Wikis don’t allow you to single source the content.
Wikis are poor at translation.
Wikis don’t get enough edits from users to justify the platform.

I want to address some of these objections, if only to provide notes for myself.

Although many people don’t realize it, content re-use in Mediawiki works much the same way as it does with help authoring tools. If you put content in a template, you can re-use that template in any other page as much as you want (it’s called transclusion with Mediawiki). You can also embed pages inside of other pages.

What you can’t do is easily push the content to a nicely printed manual or do other multi-channel publishing (at least not with Mediawiki). You could, however, come close by embedding pages in a specific order and then customizing the print CSS stylesheet. But in all the feedback I’ve seen on forums and through email, I have yet to come across a request for a printed manual. I do often create one-page quick reference guides that people can print. These seem to satisfy the need for a print experience of documentation.

With translation, while help authoring tools may package up all the essential files and make it easy to export and reimport those files, I don’t think wikis are impractical for translation. Look at Wikipedia, after all. How is it available in so many languages if wikis aren’t suitable for translation? What’s more, wikis allow for community translation in a way that help authoring tools usually do not. Many people from the community can work on translating pages, and they can translate as much or as little content as they want.

Finally, as for the argument that wikis are underused, I think this is because people misunderstand volunteer dynamics. Just adding an Edit button on a page doesn’t mean people are going to edit the content in useful ways. In the same way, if you walk into a room of people and issue a blanket call for volunteers to work on cleaning up the roadside, not many will do it.

Managing volunteers is all about relationships and personal invitations. If you have a group of people who have volunteered to do writing, and you invite them to do specific writing tasks, they do it more often than not. Getting people to participate requires management. It requires some relationship building and follow-up. But it’s possible, and the effects can be somewhat staggering.

I don’t mean to discuss the merits of wikis at length here. Certainly wikis have shortcomings. For example, with Mediawiki, the access model seems a bit narrow-minded to me. You can’t control access at the page level; everything is either open or closed. Skinning themes is also more complicated than it needs to be. But it’s a platform that has many more advantages than disadvantages. And the success of Wikipedia seems to trump all possible arguments against the viability of wikis or Mediawiki as a tool for knowledge.

Conclusion

It’s too early to tell whether moving back to wikis will solve the resource problems I mentioned earlier. But I’m hoping that I will have learned enough about engaging volunteers to make wikis finally work for me.

I know wikis aren’t ideal for every situation. If collaboration isn’t important, if you aren’t stretched thin with resources already, and if your internal technical writing team can adequately handle all the documentation needs, can cover all the various perspectives, issues, scenarios, and other topics that your audience wants to see addressed, then a traditional help authoring tool would be a good fit.

But in my experience, the need for documentation is only growing. The idea that a single writer can adequately provide instruction for a system that thousands of people use — people in different roles, environments, locations, perspectives, and business contexts — is an idea that falls short for me time and again. When I sort through feedback and forum threads, my eyes are open to all the gaps and unanswered questions in my documentation.

Collaboration and interaction are key characteristics of the web for a reason: when you allow others to contribute information, the value of the information grows. It becomes more accurate, more comprehensive, and for those who contribute, the documentation becomes their own. This sense of ownership is perhaps the most powerful effect of a collaborative platform. When your users feel ownership about the documentation, they are more inclined to tend and care for it in the long term. In contrast, internal technical writers often move on to another project after one finishes.

Blog Sponsors

Diverging Directions for Tech Comm: Social Media or Structured Authoring

Tom Johnson — Thu, 09 Jun 2011 06:35:14 +0000

Two powerful trends in tech comm seem to be moving in different directions: social media and structured authoring.

I have used a wiki as my primary format for documentation for the past year and a half. I tried to corral a group of volunteer technical writers to edit and update the wiki, because I embraced the idea that collective intelligence beats the individual thinker in the long run. But even the most advanced wikis don’t have a structured authoring backend. With wikis, you compromise single sourcing, content re-use, and multi-channel publishing. So you really can’t move in both directions well. I feel like I’ve had to choose whether I’ll pursue structured authoring or social media formats for my help content.

While at the STC Summit, I kept thinking about metadata and the idea of sorting content semantically by queries that leverage the metadata. I asked more than a dozen of the smartest people in tech comm about this, and I came to the conclusion that if I ever wanted to do it, I’d need to embrace an XML format and develop custom semantic tags.

One evening I had a dinner conversation with Sarah O’Keefe about moving to XML. Sarah explained different ways to write XML and how to query the XML even when it’s not structured as it should be. She grabbed a napkin and drew the following:

The code Sarah drew for me on a napkin.

Yes, I kept this napkin! It was the best souvenir from the STC Summit. It’s funny because when she asked for an example of one of the metadata values and properties I wanted to use, I said role as the value, with editor as the property. But I must have mumbled it, because she wrote “elder” as the property instead.

After the conference ended and I returned to work, I decided to abandon my wiki and move all my content into our Mark Logic database, which stores content in XML. This is LDS.org’s backend anyway. To do this, I would need to convert all my wiki topics into XML and add the appropriate metadata to run all the custom queries and provide the faceted filtering I wanted.

I spent several weeks coming up with the right metadata and applying it to all my topics. I was basically saying goodbye to Mediawiki and the idea of collaboration. I would structure my content in XML, and I would be the sole author. Not that many community volunteers edited the wiki anyway, but there was always the possibility that some day it might take off. Still, I had given the wiki almost 2 years without seeing fruit. It was time to try something else.

When it finally came down to the time when I needed to convert my content, I learned that the web development team had created special help templates for me. These templates included a WYSIWYG editor where I would basically create pages. Further, I wouldn’t even be the one converting the content. A special web development team would handle it all, populating the templates and creating pages, and even if I wanted to touch the content I could not. They planned to pull it directly from the wiki.

What about all of those metadata fields that I had labored over? I had to pitch the whole idea about semantic structure and findability again. In the end, they penciled in a future task in a later sprint to expose certain metadata fields in the templates for the web publishing team to use. The custom queries will be a future request, once my content is in XML.

I thought I would be swimming in XML and coding until my eyes turned blue, but it turns out that this approach is even less techie than the wiki. For the time being, I relinquished my publishing control.

I’m eager to see if the new format yields higher visibility and findability for the help. It probably won’t be until the end of summer when I can evaluate whether the migration from wiki to XML was a good idea.

In the meantime, I have not altogether abandoned the idea of collaboration. I’m a project lead for a community LDSTech project that is more community-sourced than my wiki ever was. I have more than a handful of writers creating and submitting articles.

But hoping someone will land on a help page, realize its a wiki, log in and make intelligent updates is a dream that only few groups have ever achieved (most visibly, Wikipedia). The promises and potential of structured authoring, with faceted filtering, semantic structures, and intelligent queries, seems to outweigh the attempt to collaborate efforts across large groups using wikis.