The difficulty goes beyond melding diagrams and flowcharts with your text, too. How about using visuals and words to present complex material? While it’s been done for decades, the results have varied from being quite effective to not quite hitting the mark. And if you’re not a very visual technical communicator (it’s OK, I’m not incredibly visually oriented) doing the job well can be challenge. To say the least.

If you’re willing to take the time to learn how to effectively meld words and images, then you’ll want to give the book Wonderful Life with the Elements by Bunpei Yorifuji a look. It’s described as:

an illustrated guide to the periodic table that gives chemistry a friendly face

And the book also, whether the original intention was there or not, provides a solid template for explaining a complex topic by melding text and visuals.

Let’s take a brief look at Wonderful Life with the Elements.

Step by step

Each chapter of Wonderful Life with the Elements builds on the previous one. It starts out by introducing a number of common elements, then illustrates how those elements have been used through the ages. Not just by humans, but by nature as well. As I mentioned a few paragraphs ago, it’s not a new idea and has been done before. But what Yorifuji has done is use the visuals to tell a story and not just illustrate what the reader is (or should be) learning.

That storytelling approach makes the subject matter more accessible and relates it to the reader’s everyday life. Going back to the first couple of chapters, showing how elements have been used by people over the years makes the idea of the periodic table a bit more relevant. It sure beats looking at a bunch of arcane combinations of letters – like Fe, Ra, and Uus – in a table and trying to figure out what they all mean.

A picture is worth a thousand words, but …

But unless that picture has context, it’s meaningless. Yes, text is also important. Wonderful Life with the Elements, as I mentioned earlier, combines text and visuals. But the text melds with the images that it supports – there’s just enough explanation to complement the images, but it doesn’t distract too much from them.

Here’s a sample page out of the book, which explains how some elements can combine to do harm:

Lessons for technical communicators

Wonderful Life with the Elements is a solid guide to how to use visuals to teach and explain. Again, the technique used by the book is nothing new. Illustrated, and sequential art, manuals have existed for decades. But the book also adds the element of story to explain a complex and difficult subject.

And the emphasis of Wonderful Life with the Elements is simplicity. The drawings are simple, the text is easy to read, and it makes dealing with the subject matter – in this case, the periodic table – a whole lot easier. While many, and not just academics, will scoff at using these techniques, at no time does the book talk down to the reader. Quite the opposite. It starts from the premise that the reader is intelligent and is looking to learn the periodic table quickly and efficiently. Wonderful Life with the Elements helps them do just that, in a novel way.

Yea or nay?

I say yea. I found Wonderful Life with the Elements to be a refreshing look at a subject the vexed me in high school. On top of that, I saw the potential for the book’s approach to be applied to technical communication.

Admittedly, an illustrated guide like Wonderful Life with the Elements isn’t suitable for all technical topics. It might even alienate some readers. But if done properly, an illustrated guide can educate, and help make that education stick.

If nothing else, this book is worth studying to learn a new wrinkle on an old approach to teaching complex topics in an easy-to-understand and easy-to-follow way. And isn’t teaching what technical communication is all about?

No, we haven’t been kidnapped by aliens or succumbed to some nasty fate. We’re alive and definitely kicking.

Since last May, we’ve gone through a lot of changes. Actually, many of the changes started before then. And most of those changes have been good. Some of them great. None of them boring. In fact, the last 12 to 15 months have been a bit of a whirlwind both personally and professionally for both of us.

We’ve been exploring new paths and walking towards new horizons. And our professional focuses have changed.

Aaron has moved into customer engagement and product marketing, areas in which he’s been interested for quite some time. And they’re areas in which he has quite the aptitude. Customer engagement and product marketing allow Aaron to combine his (considerable) people and technical skills, and are areas in which he’s finding new and exciting challenges.

Scott recently sold all his worldly possessions, packed up the family, and moved to New Zealand. By doing that, he’s realized a dream he and his wife have had for over a decade and a half. And while Scott’s still involved in technical communication (as a team lead at a software firm in New Zealand), he’s gradually shifting away from tech comm and is focusing on blogging, writing, and coaching/consulting.

So, what about DMN Communications? We’re keeping the company alive, though dormant. Even though our careers are moving away from technical communication, it’s still a part of our professional lives. DMN Communications is still a vehicle for consulting as a team (even though we’re oceans apart).

You never know what will happen.

Photo credit: johnnyberg

To do that, I turn to others who know a lot more about wikis than I do. Folks like Stewart Mader, Alan J. Porter, and Sarah Maddox. And it’s Sarah Maddox, or at least her new book, that sparked this blog post.

Being the aging, jaded person I am I don’t get excited about much. When I learned that Sarah was working on a book on using wikis specifically for writing documentation I got excited. As a technical writer for Atlassian (the folks behind the Confluence wiki), Sarah lives documentation and wikis — all of Atlassian’s documentation is delivered with a wiki. I was expecting a comprehensive look at using a wiki for documentation. And I wasn’t disappointed.

Let’s take a closer look at Confluence, Tech Comm, Chocolate.

Jumping in

Confluence, Tech Comm, Chocolate is an end-to-end tutorial on using a wiki for documentation, written in a lively style. It starts off with an introduction to wikis and takes you on a quick tour of Confluence. From there, your learning begins. Each chapter is a lesson, walking you through what you’ll need to know to successfully use a wiki to write, edit, review, and deliver documentation. At end of each chapter is a recap of important points that were covered, along with more than a few references.

As I said a moment ago, the book is written in a style that’s easy to read and never boring. Walking you through the book is a character that Sarah created named Ganache. She’s a technical writer (surprise, surprise!) and it’s through the filter of Ganache’s experience that you see how to effectively set up a wiki for documentation.

Be warned that this isn’t a short book. Confluence, Tech Comm, Chocolate weighs in at 477 pages. But unless you’re an expert wiki user, you’ll learn something from many of those pages. It’s also heavily slanted towards users of Confluence. But you can apply the information in the book to other wikis. More on this in a bit.

Now that the preliminaries are out of the way, let’s jump into some of the section of Confluence, Tech Comm, Chocolate that I found interesting and useful.

Writing and structuring information

Well written and well structured documentation is far more useful to readers than unrelated bits of content. As Sarah writes:

Isn’t a wiki just a puddle of chaos? Doesn’t it always look like an unimaginative scrabble of words, with no form to enhance the meaning? Not necessarily!

To help you avoid creating that puddle of chaos, Sarah spends several chapters looking at how to plan, structure, and create content on a wiki. That involves planning your wiki, changing its appearance because looks can matter, and to reuse content whenever possible.

Also, wikis are prime candidates for creating documentation via topic-based writing. Each page can be a discrete piece of content, connected with other content via links and cross references. Just about anything you can do in tools like FrameMaker or Flare, you can do on a wiki. Including delivering online help, a subject to which Sarah devotes an entire chapter.

Engaging your audience

As I keep pointing out to people (some of whom should know better), technical communicators aren’t creating documentation for themselves. We have an audience that we need to engage and capture. That’s not easy. But luckily there are tools out there to help us.

Like what? Like social media, for example. As Sarah points out:

Social media offers new ways for getting readers involved in the documentation and for getting technical communicators involved with their readers. Never before has it been so easy to engage with so many people at once.

How? By:

• Making readers aware that the documentation exists.
• Getting feedback from readers.
• Influencing what people say and think about documentation.
• Making documentation one of the first, if not the first, point of contact

You can do that, as Sarah points out, by not only getting the attention of internal teams and bloggers on the wider web, but also by using tools like Twitter to publish tips and point to information that readers can use.

But engaging your audience doesn’t stop with pulling them into your documentation. If you can, get them involved in leaving comment or, even better, adding to the documentation. Even nowadays, I know more than a few technical communicators who are loathe to allow reader to touch their documentation. But as I pointed out earlier and elsewhere, it’s not our documentation. We’re writing it for our readers, and many of them have insights that we can use to improve those docs.

Sarah devotes a whole chapter to this, called “Updates by everyman,” and offers some solid advice on why you’d want to involve your readers in updates, as well as information on copyrights and intellectual property. That chapter cleared up some of the questions on this subject that have been nagging me for a while.

But I don’t use Confluence …

So what?

I read a short review of Confluence, Tech Comm, Chocolate at an online bookseller. The person who wrote that review claimed that he couldn’t figure out how to apply the lessons of this book to other wikis. That left me scratching my head. Sure, this book is filled with examples of the features and functions related to Confluence but if you know your wiki (or are willing to learn about it) then you can adapt a lot of the information in this book to your tool of choice. Like what? How about, for example:

• Plugins — Most wikis support them. And while they might not be as powerful or as flexible or even as numerous as the ones available for Confluence, chances are you can find plugins that suit your needs. DokuWiki, for example has plugins that enable you to create a book by selecting various pages or to create and edit SVG images.
• Namespaces — All wikis support namespaces. Namespaces enable you put compartmentalize your documentation. You can have namespaces for user guides, administrator guides, and online help. Never the twain shall meet, unless you explicitly link between them.
• Importing content — Not all wikis support this, but the ones that do often do it well. MindTouch, for example, has a feature that lets you import a CHM file.
• Content reuse — A lot like snippets in Madcap Flare or insets in FrameMaker, most wikis allow you to reuse content. You can read about how I did that with Twiki here.

And those are just the examples that popped into my head as I was writing this post.

The lessons of this book aren’t restricted to the tool. Earlier, I mentioned the chapters which discuss how to engage readers. And if you can’t find a way to take the information in chapters 6 and 7 (on developing content and structure & style, respectively) then I suggest you find someone who can.

Adapting the information in Confluence, Tech Comm, Chocolate to your wiki might take a bit of time and thought, but it’s worth taking that time and doing that thinking.

OK, where does chocolate come in?

If you’ve ever read any of Sarah’s blog posts or tweets, you know that chocolate plays a role in her personal and professional lives. It’s a treat. It’s a good energy boost. And it’s a good way to engage (I hate to use the word bribe) developers and subject matter experts.

Throughout the book, you’ll find little sidebars containing quotes from various technical communicators on what role chocolate plays in their professional lives. If nothing else, those sidebars offer a nice break. And some good ideas for snacks!

Summing up

While I read the book from cover to cover (except for the index), I didn’t look at everything in the Confluence, Tech Comm, Chocolate in this review. There’s a lot more between the covers than what I’ve outlined above. And it’s useful whether you’re new to using wikis for documentation or if you’re an experienced hand.

Confluence, Tech Comm, Chocolate bridges the gap between the theoretical and practical sides of implementing a wiki for documentation. And its tech comm focus is something that makes it an excellent companion to books like WikiPatterns, Writing in the Open, and WIKI: Grow Your Own for Fun and Profit. If you’re a technical communicator looking for solid, practical advice on implementing a wiki for documentation then grab a copy of this book. You won’t regret it.

Of course, the nature of research has morphed since I went pro all those many years ago. I remember spending a lot of time in the library or on the phone digging up information. Then, the Internet came to our computers and changed the game.

In the early days, researching on the web involved either copying and pasting information into a text editor or word processor file, or jotting notes on to paper. Thanks to web-based note taking applications like Evernote, that became a whole lot easier.

But copying and pasting information into Evernote isn’t the most efficient way to do things. Why not let your browser and Evernote work together? You can do that with two browser extensions for Evernote called Web Clipper and Clearly.

Let’s take a closer look at them and how they can be a useful addition to the tool kit of any writer, technical or otherwise.

Web Clipper

Evernote Web Clipper does just what it says: it clips information from a web page and saves it to your Evernote account.

All you need to do is install it and you’re literally a mouse click away from saving useful or interesting information that you find on the web.

When you install Web Clipper, it adds an icon to your browser’s tool bar. Here’s what it looks like in Chrome:

When you’re on a web page containing information that you want to save, just click the icon. After a second or so, a small window opens.

Here, you can do a number of things like:

• Choose the Evernote notebook in which you want to save the page.
• Add tags or comments to the note. Tags make it easier to find notes in Evernote, and you can use comments to note where you found the information.
• Choose whether you want to clip the article, the entire page, or just the URL.

When you choose to clip the ariticle, Web Clipper only copies the text and any graphics in the main portion of the page. Choosing to grab the entire page … well, grabs everything. Cruft and all.

I have two minor beefs with Web Clipper. The first is that it sometimes doesn’t give you every option for grabbing content. Sometimes, you can only grab a URL or the entire page. Sometimes, everything. Not a big deal, I admit, but sometimes that can be frustrating. The second is that it’s all or nothing – you can’t just grab a selection from an article or web page.

Using Clearly

Remember when I mentioned that you can grab full web pages, cruft and all, with Web Clipper? I don’t know about you, but often that cruft annoys me. And not just when I’m clipping information to Evernote.

All of those additional page elements – like graphics and ads – are distracting. They can slow my reading down. Especially when I’m reading on my Chromebook, my smartphone, or my media player. Which is why the folks at Evernote came up with Clearly. Clearly …

… makes blog posts, articles and webpages clean and easy to read

Like Web Clipper, when you install Clearly you get an icon on your tool bar which looks like this:

Click the icon and Clearly creates a version of the page with only the text of the page and any graphics. All the cruft is removed.

That’s a lot easier to read, wouldn’t you say?

Combining Clearly with Web Clipper

Clearly comes with its own clipping tool. I don’t like it all that much – it only saves the content to Evernote. There’s nothing wrong with that, but I prefer to be able to choose the destination notebook and to add tags or comments before I save a clip.

Guess what? You can use Web Clipper with Clearly. They make a powerful pair. Just give a Web page or article or blog post the Clearly treatment, then click the Web Clipper icon. Choose your options, and save the clip.

You get the best of both worlds – the ease of reading of Clearly and the flexibility of Web Clipper. And all it takes is a couple of clicks and a few keystrokes.

I’ve been using Clearly and Web Clipper together since Clearly made it’s appearance a few months back. It’s made reviewing information on my mobile devices, and reading on both those devices and my laptops, a lot easier.

The ability to add tags and comments is useful, too. Tags I’ve mentioned before. With comments, I’ve gone beyond using them just to note where I found some useful text. I’ve also started using comments to pinpoint where in an article or post the information I’ve dug up should go, or to note a paragraph containing something worth using.

Do you use Clearly and Web Clipper? How are you using them? Share your ideas by leaving a comment.

Call it what you will, but most of us fall into the comfort of a routine now and then. Yes, the oft-talked-about comfort zone.

There’s nothing wrong with that. But I find that inhabiting the comfort zone can get boring. Actually, worse than boring. You’ve probably felt the same way. The work is easy to do and feels more like typing than actual writing. Or, you feel the need to move into areas other than just pure technical writing.

Lately, I’ve been feeling that I’ve ensconced too snugly in my own comfort zone. As part of something I call Phase 3 (more on this in the coming months) and as part of the New Cruelty, I’ve been experimenting with ways of bursting free of my comfort zone.

You can burst out of yours too. And doing that just might refresh you, your technical writing, and your career.

Curious? Then read on.

Proceeding with a plan

Moving out of your comfort zone is difficult. It takes a conscious effort. To do it effectively, you need a plan.

Your plan doesn’t need to be elaborate or detailed; it can be, though. Just think about what you want to do and then start with small steps down that road.

Like what? For example, maybe you primarily work on user documentation for enterprise applications. To move outside that comfort zone, you might consider blogging or writing short manuals or articles for commercial products. Start small. Write short pieces using language that’s more casual than what you’d use with your usual audience. Then move on to writing longer pieces.

Or consider contributing to an Open Source project like FLOSS Manuals. Whenever I take part in or facilitate a book sprint, I get a different perspective on documentation. I also feel a bit less jaded about my profession and even learn a thing or two.

Get into the rhythm of what you want to write, then build up.

Moving off on a tangent

Earlier, I mentioned Phase 3. It’s going to be a big change in my life, one that some of the fives of people who read this blog know about.

As part of Phase 3, I’m seriously considering moving into a couple of areas that are really outside my comfort zone. They involve writing to a degree, but also skills that I don’t currently have. This is where the New Cruelty comes in: trying to pick up those skills.

(If you want the details, you’ll need to wait a little while. I don’t talk about plans that I’m currently formulating. Nothing personal …)

As I wrote a couple of paragraphs ago, I’m planning on doing one or two things that interest me but which outside of my usual sphere. It’s not going to be easy, but I sure am going to try.

You can, too. Maybe you want to add photography or technical illustration or writing API documentation to your set of skills. The only way to do that is to learn. And practice. And practice some more. It will definitely take effort. And it could be expensive.

The rewards, though, are definitely worth it.

Expect to fail

I can tell you from experience that not everything you try will work out. In fact, failure is a distinct option.

And that’s fine. Don’t let failure get you down.

Failure is useful. Failure is instructive. Failure helps you grow.

Breaking out of your comfort zone isn’t just something you should try. Sometimes, it’s something that you need to do. It will make you a better, more rounded person and writer.

Thoughts? As always, your comments are welcome.

Photo credit: samplediz

But you can apply topic-based writing to work outside of our profession.

As you may or may not know, I do quite a bit of freelance writing. And sometimes, I have an idea for a non-fiction writing project, but am only able to chip away at it bit by bit? That sometimes feels like it happens a bit too often.

I also find that with projects like that, I write in bits and pieces — a few sentences or paragraphs here and there — and never get anything finished. I have chunks of writing, but can’t really pull them together.

Yes, that’s where topic-based writing comes into play. It can help you pull together all those chunks of content that you’ve been pecking out into something tangible.

Have I got your attention? Then read on.

Topic-based writing: a quick refresher

If you’re familiar with the subject, or if you use topic-based writing in your daily work, feel skip this section.

With topic-based writing, a piece of documentation is broken down into its component parts. Each of those components is called, as you’ve guessed, a topic. A topic can be a lump of overview information, a procedure, and the like. It can be a single sentence, one or more paragraphs, or longer.

Each topic stands on its own. It’s not related to, or reliant upon, any of the topics that come before or after it. You can stitch topics together in a number of very interesting and unique ways.

As far as documentation goes, you can have a store of topics. Then, you can combine them to create various types of manuals.

Applying this to other writing

That’s all well and good for technical writing. But how can you apply this concept to other forms of non-fiction writing? Actually, that’s fairly easy.

Take all of those bits and pieces that you’ve been writing — whether they’re in text files, word processor documents, or in a paper notebook. Treat those bits and pieces as topics. Then combine them into one large document. Of course, you’ll want to put them into a logical order …

Chances are, you’ll have at least an article’s worth of content. The problem you’ll encounter is that after you’ve stitched all of those topics together, the final product will seem very disjointed. That’s one weakness of topic-based writing. However, that’s a problem that’s easy to get around. Just add segues and linking material wherever it’s needed.

A real-world example

No, this isn’t all theory. I’ve used topic-based writing with other forms of non-fiction. How?

A while back, I had a tough week or so that took its toll on my writing. In fact, there was a day that I officially declared a write off. Definitely not a happy thing when you’re staring down the barrels of several deadlines.

One article in particular was rather slow in coming. It was an assignment from a gadget magazine: I had to write a 1,200 word article on 10 recommended gadgets for Christmas. One hundred words per gadget, plus recommendations and introductory and concluding material. That’s not a lot of space, but it wasn’t a problem. I’ve done articles like that before.

But those 100 words … They didn’t seem to want to come the way they usually do. And to keep each description in the 100 word limit, I decided not to fool around in word processor with word counts.

I wrote each description in a text editor, and saved those descriptions in individual text files. Doing that made it easier to reach and stay within the word count for each gadget.

Once everything was written, I pulled the files together and pasted them into a word processor. I was able to do this quickly and easily because there was no linking material between each description. All I needed to do was add a little information to beginning and to the end.

Since then, I’ve done that a few more times. And, guess what? Topic-based writing not only saved my bacon, it made getting the work done a lot easier.

In fact, one of the ebooks I’m working on (titled Project A) is being written using the topic-based technique. Each chapter is a topic. That gives me a lot of flexibility in arranging and re-arranging the order of chapters. I don’t have to worry about re-writing connecting material. Once I’ve found the optimal mix, I can add that material and then publish.

Taking this a step or two further

By tackling one or more writing projects in this way, you’re opening the door to creating a library of topics. You can use what’s in that library to quickly assemble articles, or target existing ideas (with a few changes) to multiple markets.

The biggest problem you’ll face is that you’ll have a hard time keeping track of all of your topics once your library begins to grow.

Thoughts? Feel free to leave a comment.

Take a moment, sit back, and let Uncle Scotty tell you one of his stories:

In November of that year, I started a six-month technical writing contract with a financial firm here in Toronto. The pay, while not the greatest, wasn’t too bad. And having that firm on the client list wouldn’t have hurt either. During the weeks that followed, I got a lot of good feedback about my work and was making good progress on my project.

Then on a Wednesday in early December, 2010 (a month, to the day, from when I started, in case you’re wondering) I got a call from HR. I went to their offices and before the very agitated looking HR person could open her mouth, I said I think I know what this is about. Then, pointing to the envelope on her desk, I further perturbed the poor woman by saying I assume that’s for me …

I, along with 3/5 of the company’s documentation team, was let go then and there. Another department or two had been gutted in the previous day or so, too. But I wasn’t worried. I’d been there before. This was the first time this happened as a contractor, though.

It being December, I knew that there wouldn’t be any longer-term gigs in the offing. Things usually slow down at around that time of year. But by scrambling, I was able to pull together enough short-term work to keep me going for a while.

Here are a few lessons I gleaned from that experience.

Have some money saved. Everyone advises people striking out on their own to have at least three months worth of expenses saved. Preferably more. Luckily, I’m one of those people who took that advice. I probably should have more saved (I’m working on it), but the cushion I had plus what I made with a number of freelance gigs will tide me over for the beginning of 2011 at least.

Always keep your eyes open. Even when you have a gig or two. Always make sure that you know what the market is like and are ready to adapt. You never know when you’re going to have to roll with the punches. Preparation is the best defense, especially for the freelancer.

Use your network. You probably know other freelancers, or have other clients or former clients. Don’t be afraid to contact them. It might seem like begging, but many of them understand. They’ve probably been there before. You never know what will happen. The worst thing they can say is no. But they won’t even say that if you don’t ask first.

Don’t take the low-paying gig. Unless, of course, you can’t afford to do otherwise. If you can, avoid it. Taking low-paying gigs not only saps your energy (you have to write a lot to make even a half-decent amount) but drops you on a treadmill that can be tough to get off.

Don’t give up. Sometimes it might take a while for you to snag that next gig. Don’t give into despair. It’ll be tough to hold back those negative thoughts. Yes, I am speaking from experience. Just trust in your ability. Keep trying; something will happen.

Thoughts? Feel free to leave a comment.

Photo credit: Catabu from Photoxpress

So what does this have to do with technical writing? Quite a bit. Storyboarding isn’t just for movies. You can use it for any kind of writing that has a visual flow, like screencasts or presentations.

I use storyboards when creating presentations and screencasts. Let me explain how.

Start with an outline

If you know anything about the way in which I write, you know that I’m an advocate out outlining. An outline gives me a good start at building the structure of anything that I’m writing. As I work on the outline, I can often spot weak points in my idea or where I need to shift things around.

With presentations, an outline delineates each topic that I want to cover. Visually, one topic is one slide. With screencasts, the outline breaks down each step that I want to cover.

As with any outline:

• Don’t over think it. It’s too easy to fall into the trap of trying to cover everything. That’s not possible, or even advisable. And it slows you down.
• Keep it fluid. Expect to do some rearranging and shifting.

Creating the storyboard

You can do that on paper or with software. I use a Moleskine Storyboard Notebook. You can also create a custom sheet of storyboard paper online and download it to your computer as a PDF file.

On the software side, check out Celtx, an Open Source tool for writing screenplays. It has a very good, and easy to use, storyboard feature.

When creating the storyboard, you don’t need to be detailed. Thumbnail sketches of what you want to do are often enough.

When I do a storyboard for a presentation, I point out ideas for the background of the slide and give information about the text (if any) on the slide. Here’s a sample (yes, I know it’s messy …):

With a screencast, each shot on the storyboard consists of the screen (or the state of the screen) that I want to capture and explain. One shot can be me selecting an item from a menu, another one me entering text on the screen, and the like.

I sometimes go through two or three iterations of a storyboard — adding here, trimming there, tightening elsewhere. This helps me find the optimal flow.

Once that’s done, I create draft slides or do a first run through of the screencast. Usually, this is done in conjunction with the script I’ve written in parallel with the storyboard. Again, I’ll make minor tweaks until the final product is where I want it to be,

A storyboard seems like a lot of extra work. And it can be. But it’s also a great way to capture the visual flow of something you’re writing.

Thoughts? As always, your comments are welcome.

Photo credit: wlima from stock.xchng