I'd Rather Be Writing » future

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

Matrix Foretells Future of Learning

Tom Johnson — Thu, 15 Dec 2011 14:12:05 +0000

Apparently the Matrix was somewhat prophetic in showing us the future of learning. The idea that you can download knowledge is becoming more of a reality. According to Fox News:

Scientists from Boston University and ATR Computational Neuroscience Laboratories in Kyoto, Japan, have used a functional magnetic resonance machine (fMRI) to decode the process of learning.

The procedure – known as Decoded Neurofeedback or “DecNef” – stimulates the visual cortex by sending signals that change the brain activity pattern.

For example, by placing a juggler into a fMRI machine and have them imagine juggling, scientists, can capture the brain patterns and then pass the information onto someone else. (See What If You Could Download New Skills? Scientists Say It’s Possible.)

Maybe in the future, rather than writing a manual, technical writers will get into an fMRI machine and imagine each of the tasks of an application. The brain patterns we produce will be our deliverable, the new manual.

As a side note, try reading the original article in a science journal. Then compare it with the Fox news article. Talk about dumbing down the content!

(As a related article, see Brain Waves and the Stimulation of Motivation/Creativity, a post I wrote several years ago.)

Blog Sponsors

Predicting Tech Comm’s Future for Mobile

Tom Johnson — Fri, 29 Apr 2011 14:42:03 +0000

Robert Desprez has an interesting post on How Will Technical Writing Change in the Next Ten Years. Among a few predictions, he writes the following about tech comm’s future for mobile:

We’ll all be preparing our online help for mobile devices. Smartphones and tablets are expected to start outselling computers in the near future. More and more people will be using these devices to work and will need technical assistance. I expect this is the next “big thing” for us.

I agree that mobile devices will continue to grow. Every statistic suggests that computers will become more advanced, tiny, and ubiquitous. However, given that we have more than 350,000 iPhone apps right now, and the market for technical documentation for mobile apps hasn’t flourished, why should we think mobile will factor heavily into tech comm’s future?

I do think mobile will play a larger role, but several things will need to change before mobile becomes a prominent playing field for technical writers.

The Missing App

The one app that iPhone lacks is a screen recorder app (like Camtasia Studio) to capture video demos of all these apps. I don’t mean screen capture; I mean live video that records the screen’s actions like a movie. It’s the one app the iPhone needs the most.

The only way to create a screencast of an iPhone app is to run an iPhone emulator on a Mac. Currently the developers have to load up a development environment on your Mac, or you have to borrow one of their machines after hours and record a screencast (which I actually did a couple of months ago).

When mobile devices allow you to more easily record the screen, there might be a greater need for mobile screencasts, and technical communicators (with screencasting skills) might begin to play a larger role.

QR Codes

Another big shift might be the prevalence of QR codes. Imagine hiking on a trail or exploring a city with your mobile device. You stumble across a building, a monument, or some other interesting object. It has a QR code (or something similar) on it. You hold up your mobile device and voila, immediately you’re learning about that object. These codes would enable an era of location-based documentation.

QR codes could also be handy when you’re working on your car’s engine. All of those mysterious parts — if only each part had a QR code. Or let’s say you’re taking apart your refridgerator to fix something. What does each component do or mean? If you had QR code stickers attached to each part, you could let people know more information about it.

Download a QR code app on your mobile device and take a picture of this image with the app to see the hidden message.

Field Reference Guides

The third major use of mobile for tech comm lies in the field reference guide. While you probably wouldn’t look up help information for a desktop app as you’re sitting at you’re computer, imagine if you’re wandering in the woods looking for a certain type of bird. It would be nice to have the field guide as an app that you could navigate offline as you’re wandering.

I sit at a desk all day, so it’s hard for me to contemplate what it’s like to have a job where you walk around, or where you’re frequently outside. But let’s say you’re a door-to-door salesman. It might be nice to have a product list app on your mobile device that describes every product your company sells, along with a brief description and picture.

Or maybe you’re a technician for a large company, with a lot of different devices, networks, and other technical infrastructure that you have to take care of. It would be nice to have a mobile reference guide for all the components you’re responsible for.

The perfect scenario for mobile documentation is actually in the kitchen. For cooking novices like me, sometimes recipe books use jargon like “chop the carrots in julianne style” or “blanch the broccoli” or “braise the turkey” or “cook the caramel until it reaches a soft ball stage.” It would be nice to have those recipes on a mobile device with links to more information or videos showing more detail of what it all means. I know I’d be the first one to buy such an app.

The possibilities for incorporating tech comm guides and videos on mobile devices are just opening up. The problem is that so many tech comm jobs are in software, and the sweet spot for tech comm with mobile isn’t with software. There are 350,000 apps, most without documentation, to prove that. The real opportunities for mobile lie with location-based information needs, or information needs for people who aren’t at their computers.

Blog Sponsors

THE CONTENT POOL: Move over DITA – Chaos is coming!

Tom Johnson — Tue, 09 Dec 2008 04:51:56 +0000

THE CONTENT POOL: Move over DITA – Chaos is coming!

Blog Sponsors

Technical communication, past, present and future: a review [TechScribe software documentation]

Tom Johnson — Sun, 30 Nov 2008 04:15:02 +0000

Technical communication, past, present and future: a review [TechScribe software documentation].

Corporate Migration to the Blogosphere

Tom Johnson — Thu, 28 Aug 2008 04:37:43 +0000

Looking into the future

A few months ago, I started to write a post about the cultural shift blogging would create in the near and long-term future. I didn’t get very far and quickly became mired in speculation. But when I learned today that RJ Jacquez now has a blog, I started to remember some of my predictions. Basically, it goes like this:

Amateur bloggers start to saturate Google with content that controls the reputation of company products.
Companies, fearing a complete loss of voice, start joining the blogosphere in masses.
With so many people writing and publishing daily, information grows to a ridiculous degree and becomes difficult to manage.
Search becomes the only way to find anything.
Writers, especially those gifted at SEO and content creation, and who have a lot of Google karma/page rank, become major corporate players, with more prestige than ever before.

And right about there I didn’t know what came next. I think at some point there’s a major shift and people move away from the web altogether, embracing a new form. But I couldn’t figure out the details.

Anyway, RJ Jacquez from Adobe, Mike Hamilton from Madcap Software, and Alan Porter from WebWorks all have blogs. I suspect AuthorIt will eventually launch a blog, and the dozens of other software vendors. They’re realizing that it’s marketing suicide to be offline and silent.

Although these bloggers are all intelligent, clear writers, with solid reputations to give them an authoritative presence, the question is whether they will have the creative muse to write day after day in a way that engages readers. We’ll find out.

—————-

photo from UCDavis