4J's Group - THE CONTENT POOL

The Man from P.O.S.T. - "The Where to Prioitize a Technology Decision Affair"

2012-01-26T07:41:00.011-06:00

Despite the fact that for over half of my career technology companies have (and continue to) pay my mortgage - I have always been a long standing, and increasing vocal, proponent of the idea that in deciding on any business process change or innovation the technology must come last.

A topic I devote a whole chapter to in the upcoming THE CONTENT POOL book (end of shameless plug).

At the 2011 LavaCon conference I even ended up getting a quick round of applause during the conference closing panel discussion for the statement that audience members should stop talking about tools and start talking about business need. A sign that I thought that we were making some headway.

Then yesterday I was invited on a conference call for a project that has been ticking over for nearly three years now and is not making any apparent progress. The reason quickly became apparent as conversation quickly got into the weeds about the features / functions and development efforts needed around three alternative technology options.

When I asked the basic question of what was the project's high level business objective, no-one could actually articulate it. Was this a project for the customer communication,, or was it a project to prove that something could be done using existing technology? Again, no clear response.

Over lunch afterwards, a friend reminded me of the acronym POST developed by the Forrester's consulting group. P.O.S.T.

Forrester's created the P.O.S.T. approach as part of developing a corporate social network strategy - but I believe it applies equally as well to the world of content strategy (Of which social network content should be a part anyway).

P. = People
O. = Objectives
S. = Strategy
T. = Technology

Seems obvious doesn't it. Start with those who have a need, figure out the things you need to do to fill that need, develop a strategy to do it, and then think about the tools you can use to do it.

You should be thinking along the lines of "We need to decrease the time it takes to get our content changes into the hands of our customers," not "We need to install Wizgadget3.0."

Or as my lunch companion neatly summed it up -

If you put the "T" first, all your are left with is a P.O.S.

Every Presentation, Ever: A Communication Failure?

2012-01-19T13:49:00.005-06:00

I have spent, and continue to spend, a lot of my professional life either giving, or sitting through presentations. I have seen every one of the communication failures parodied in this video.

After I'd watched the video and smiled in recognition, and even winced occasionally about things know I've done in the past. I started thinking about the title.

Is every presentation ever given an exercise in communications failure?

I would submit that the vast majority are - sure there are good ones (see the various TED talks for instance), but most presentations are simply a dry regurgitation of facts and ideas that could be better expressed in much more entertaining and different ways.

How?

By focusing on the speaker, not on the PowerPoint.

Think about the conference sessions you remember most - I bet it was the ones with the energtic, passionate, articulate speakers, rather than the ones with the prettiest slides. I have seen a growing trend amongst top rated speakers and presenters to just use single image slides acting as a backdrop to a particular point as a way of getting the audience to focus on them and the message they are delivering. I even have spoken to several other regular conference speakers about dropping the use of slides altogether, but conference organizers seem to get scared when you say you don't have any slides.

During the course of the year I attend two distinct types of industry events, first there are the technical and business conferences, then as a pop-culture writer there are the the various conventions. For as long as I have been attending science-fiction and comics conventions the default way of communicating with the audience is to have a panel of guests discuss a particular topic in which they have a stated interest, or experience. No PowerPoints, just people discussing what they know and what they are passionate about. The results are invariably both enlightening and entertaining.

Yet business conferences are still dominated by the "person in front of a slide deck" model. - Why? Over the last couple of years I've been lucky enough to be invited in a few business conferences that have experimented with the panel approach (usually just one or two in a program dominated by presentations), and in every case they have been well received, and a joy to participate in.

But it doesn't necessarily need a panel to get that same effect. I mentioned the TED talks earlier - many of the most viewed videos are of a single person on stage, just talking. Sharing ideas with a passion.

Of all the presentations I have ever sat through the most spell-binding was from graphic design guru Edward Tufte who spoke for a whole day on the subject of graphics, and never once used a PowerPoint slide.

Instead of "presenting" information and hiding behind slide decks we should be encouraging expression of ideas, conversations, and discussion. - That's what communication is really about.

That Was The Week That Was ....

2012-01-06T14:49:00.003-06:00

I'm not sure I could have asked for a better first full week of the New Year. No matter how I look at it 2012 looks like it's going to be a promising, exciting, and busy year in the world of Content Strategy and Business Communications in general, and on a personal level for 4Js Group as well.

Let's take a look at what made this week such a perfect start to the year.

I kicked off the week by delivering the final manuscript for "THE CONTENT POOL" book on Content Strategy to the fine team at XML Press for final copy edits, indexing, and layout. - We are looking at publication in the first half of the year. - As soon as we have nailed down a date I'll post it here and on my twitter accounts. - I'll also be posting updates here as the book goes through the final stages before publication.

Then the fine folks at MindTouch issued the list of what they considered the most influential people in the Technical Communications and Content Strategy industries. I was delighted and honored to make the list under both my own name, and as 4Js Group, alongside so many other great industry professionals.

On the conference front, it looks like I will be speaking at this year's Lavacon in Portland in October. Lavacon has rapidly become on of my favorite events of the year, and I always enjoy speaking there.

I was also invited to join a panel on "Delivering the Business Case for Innovation" at the upcoming Intelligent Content Conference in Palm Springs next month. - The conference has a great line up of speakers and subjects.

As I mentioned, overall a great week - and a great start to the New Year.

Where have all the posts gone?

2011-08-01T15:56:00.003-05:00

Wow - I just realized I haven't posted anything here since May. Over two months ago! - That's too long for a blog to go unattended, but I have a good reason.

I am deep into writing the book version of this very blog.

THE CONTENT POOL will cover, and expand on, many of the subjects I've discussed on this blog over the years. Plus I'll be adding in more from my twenty plus years experience in the Business Communications industry to, hopefully, produce a though provoking book on exactly why content is your company's greatest hidden asset.

THE CONTENT POOL is designed to help you:

Identify
Organize
Manage, and
Leverage

your content to reduce costs and increase revenue and profits.

Look for it later this year from XML Press.

I'll be posting more updates, and maybe a few extracts, as we get closer to publication.

Looking forward to the STC Summit

2011-05-09T14:05:00.003-05:00

Next week I will be in Sacramento, CA for the 2011 STC Summit. An event I've been looking forward to for many months.

Although I'm not speaking this year, I've been more involved than ever, as both Deputy Program Manager, and Track Manager for both the Web Technology and Education and Training tracks.

This will also be the first STC Summit since the publication of my book "WIKI: Grow Your Own For Fun & Profit," which will be available at the conference bookstore and at the XML Press booth.

If anyone would like to meet up for a chat, or get a book signed, then the best places to find me (or leave messages) will be at:

The STC Program booth,
The XML Press booth,
The PTC booth.

I'll also make sure to step into some sessions and visit the expo floor on a regular basis throughout the conference.

I'll also be posting note on both my Twitter accounts during the conference, so feel free to follow, or contact me, via @4jsgroup or @alanjporter

I'm looking forward to meeting up with old friends and colleagues, as well as meeting lots of new people for some interesting discussions on Technical Communications and Content Strategy.

I think we have put together a great program this year, and if you are attending, I hope you find it both informative and stimulating.

See you in Sacramento.

You know what they say about when you assume something...

2011-04-07T12:20:00.005-05:00

...that you "make and ass out of u and me." Well I feel a little like that this morning

Earlier today I recieved an email from a software vendor (who, keeping to the rules of this blog, will remain nameless) that in order for them to issue me with a license for a new piece of software they needed the "Host ID" of my Windows laptop. - That was is it, a one line request with no further explanation.

Now about 70% of my time is spent on MAC devices of various types, MacBook, iPad, iPhone. I haven't seriously played around with a Windows machine in years - I had forgotten how to find the Host ID. Clicking on the My Computer icon and looking at Properties, which seemed to be the logical thing to do, was no help at all. So I sent off a quick email asking how exactly I was expected to find this elusive "Host ID"

"Oh, it's easy" came the reply. "Just open a command prompt, run the ipconfig/all command and look for the Phyisical Address it returns - that's the Host ID."

Hang on a minute - so the thing you initially asked me for isn't even called that, and you expected me to know that plus, I needed to go to the OS, and remember a command line I may never have used in my life!

Talk about making assumptions.

OK the end process was in fact easy - but then most things are if you know how to do them. Just beacuse you, your engineers and your support personal maybe confortable working in a partcicular environment, don't assume that your customers are just as familar.

Making yourself look like an "ass" and making your customers feel like one (even if it's only for a few seconds) is never a good idea.

Technically incompetent or just bad design?

2011-03-17T15:41:00.005-05:00

Last week I suddenly noticed that the Dell laptop I use for certain contracts was no longer picking up my home office wireless network. In fact it was telling me it was connected to an unrecognized public network without internet access. No matter what I tried I couldn't get it to disconnect from that network and pick up the wireless.

On Tuesday afternoon I plugged the laptop directly into my ethernet cable and spent several hours disabling, and enabling network adapters, rebooting modems, and frantically googling various scenarios. Most of which told me the culprit was a well known Windows 7 bug related to a rogue ID file that showed up in the Windows Services menu. Except I couldn't find that file anywhere on my machine. In the end I just reset everything and resigned myself to spending an afternoon on a help desk call.

But first I needed to be on-site at a client's facility. Thinking the problem might be my home network, I took the laptop along hoping to connect to the client's wireless - no such luck. I mentioned the problem to several people, and no one had any suggestions.

Then about 5 minutes before I decided to call the Help Desk someone who has the same model laptop asked me if the wireless switch was off.

What wireless switch?

Ah that one!!

A switch that in the five month's I've had the laptop have never even noticed.

From a communications perspective a couple of things sprung to mind from this incident.

How about putting up a warning dialog on screen at boot up when this switch is switched to the off position (maybe with a location diagram) instead of leaving it to Windows to think it has connected to an untrusted network? Would have saved sveral hours of frustration. BTW when the switch is OFF it displays a red background - but let's face it, who looks at the side of their laptop on a regular basis?

How about making switches a different color, better labeled and slightly more obvious? Most people reading this probably know I'm a big advocate of using symbols to communicate. But make them big enough and clear enough. For a guy of a certain age who wears bifocals, how am I suppose to know what that is?

Oh and who puts a switch that can disable a major feature in a position where it can slide on and off through the process of picking up the lap top and sliding it into a case? Not exactly a well thought out design there.

The Force is strong in this Content.

2011-02-03T19:52:00.003-06:00

I, like many of my friends, linked to, and shared, the video below today on our various Social Network accounts. I guess we did it for a few reasons:

It's funny.
The kid is cute.
It leverages a shared pop-culture reference that we all (well at least my friends) can immediately relate to.

But later in the day I started to think about this video in terms of content strategy and marketing.

Just before I wrote this post I checked some numbers on YouTube.

This video was posted on February, 2nd - just one day ago. It has already posted some impressive numbers:

2.3 Million views
605,000 posts on Facebook
29,600 links from Twitter
23,705 "likes"
over 3,500 user comments.

Why?

Partly for the reasons I mentioned above. In short it's great content that people enjoy and want to share. And that's the key to a marketing message like this going viral - you need good content that the community is happy to recommend and share.

But also it plays across markets, and across language barriers. Of the 1 minute 2 seconds running time only, 8 seconds uses text that would need translating. There is no voice over to be translated or actors to be dubbed. It's all done through the power of images and music.

Using different media types in this way can be (if you will excuse the pun) an effective force for making your content connect with your audience.

Webinar: Collaborate Your Way to More Effective Customer Support

2011-01-31T17:07:00.005-06:00

Join Scott Abel, The Content Wrangler, and myself, THIS FRIDAY (February 4th) for a lively discussion about the changing face of customer support on the web. You’ll learn how innovative organizations are leveraging the power of collaborative authoring, user-generated content, social currency, feedback and ratings to improve customer service and support.

You’ll discover the importance of collaborating with your customers to produce experiences that meet — even exceed — customer expectations. And, you’ll find out how collaborative support communities can help organizations create loyal customers, improve productivity, increase sales, and reduce expenses.

Hosts MindTouch will be is giving away a FREE COPY of my book of “Wiki: Grow Your Own For Fun and Profit” to the first 50 attendees to the live event.

Register Here. Today!

The Return of the LP & what it may mean for Content Delivery.

2011-01-06T20:02:00.003-06:00

I think it was generally agreed among my family that the coolest present I received this Christmas was the one my eldest daughter bought me. She ignored everything of my Amazon wish list, and instead proved that she did in fact listen to her father when he went off on one of his nostalgia trips about the music of his youth. She bought me a turntable. Yep one that actually could play the few remaining vinyl albums we had in the house (most of which now spend their days in frames on the living room wall.)

Once we had it set up and were spinning a few of the old records, I had a fairly lengthy discussion with her and her boy-friend about how a record and turntable worked, and just what was so special about the good old LP as opposed to a modern CD, or digital download. (Still seems a little funny to me that two 21 year-olds had never seen a record being played before.)

That conversation stayed with me over the holiday. Why had the LP had such a cultural impact? Records and record players had been around for decades before the sudden explosive growth of music ownership that started in the mid to late 1950s and early- 1960s. Sure the birth of rock-n-roll had a large part to play, but I thought there must be more to it than that. Then earlier this week I read the following passage by Jonathan Gould in "Can't Buy Me Love" his excellent social history of The Beatles.

"Ultimately the attribute that sealed the success of the LP in the popular market had little to do with its expanded capacity or its improved sound quality. Designated as 'packaged product' by the recording industry LPs were the first records to be sold in foot-square cardboard jackets faced with glossy cover art, which served as an alluring advertisement for the music within. This allowed them to be prominently displayed in racks or bins in virtually any kind of store; it also allowed them to be advertised as recognizable products in newspapers and magazines. (Singles in contrast, were still packaged in plain paper sleeves and sold mainly in specialist record stores.) The LP cover became a companion piece to the listening experience by providing photographs, biographical information and promotional copy."

As I've been working on my upcoming book, The Content Pool, I started to equate this great piece of social and economic history to the ideas of Content Delivery.

Think about the LP - it was still delivering the same sort of content as earlier record formats (78s and 45 singles), yes it was using new technology to deliver more in the same media, but it didn't find traction with its user base until the packaging and delivery channel was changed.

What made it work?

When the content was placed in the same location that the users frequented anyway - they no longer had to go searching for it.

It was clearly labelled and could be browsed - instead of having to read the fine print on a label, or be an expert.

It was presented along with additional information that gave the content context.

The new packaging was durable and could be accessed many times without degrading - inviting reuse.

Social networks and peer recommendation developed around the ease of accessibility and navigation.

As we all struggle with ways to present our content in new formats and on new media, maybe we can learn a few lessons from the past.

Now you will have to excuse me, I have to go turn this copy of "The Beatles at the Hollywood Bowl" over.

"Globish"? - It all sounds rather familiar

2010-12-29T17:11:00.003-06:00

Thanks to a recent Twitter post from the always entertaining and informative Stephen Fry, I recently came across the word "GLOBISH." - Mr. Fry went on to explain that "Globish" was shorthand for "Global English."

Now that piqued my interest, and after a quick application of my Google-Fu skills I found myself at the Globish website where I found out that it is described as

.... a simple, pragmatic form of English. It involves a vocabulary limited to 1,500 words, short sentences, basic syntax, an absence of idiomatic expressions and extensive hand gestures to get the point across.

And then there was this informative video.

Now this all sounds very familiar. This approach of using a controlled sub-set of English to reach non-native English speaking customers is something we have been working on in the technical communications community for decades. In fact as an idea it dates back to the 1930s.

Yet it seems that this newest incarnation of the concept seems to be getting a lot of mainstream publicity that our efforts have never achieved. Globish has been the subject of stories by, among many others, the BBC and the New York Times. I can never recall any mainstream press being interested in the ideas, concepts and benefits of Simplified Technical English, or even the government sponsored Plain Language initiatives. - I wonder why that is?

Paying the Ferryman - The cost of putting your content in someone's hands.

2010-12-21T11:21:00.008-06:00

As part of the research for my next book for XML Press book (Which like this blog is also entitled THE CONTENT POOL.) I was having a conversation with a couple of people at a large manufacturing company about the cost of their documentation; at the start of the conversation I was expecting to hear all about the software they used to author, manage and publish their information, or even about the cost of training and retaining skilled technical communicators. But the conversation very quickly turned to one aspect of technical publishing that most of us (and I include myself in that) often completely overlook. - The cost of actually getting the information into our customers hands.

For this company their largest publishing related cost is simply Postage.

When we talk about modern technical communications and publishing systems, processes, and technology, we tend to think about digital creation and delivery. Along with that comes an assumption that most, if not all, our customers are in some way connected to the internet. There is a lot of talk (and again I'm just as guilty as anyone) of web delivery, mobile delivery and the bright digital future we are all marching towards. Yet that is a very Anglo-American centric view of the world.

Recently someone at Facebook developed a visualization of all the various Facebook connections, and the image that appeared (below) turned out to be a startlingly accurate rendering of a map of the World. Except that large areas of that map were dark. It reinforced the message that even if we are producing information digitally, we can't assume that if we are operating on a global scale everyone who needs access to our information has a wired connection.

So back to my earlier conversation. The company I was talking to uses XML and topic based authoring processes, along with content management tools, to efficiently single-source their documentation into many different deliverables.

But their products are literally used all over the world, including in some of the world's most inhospitable and remote locations. Not everyone is wired, so instead they ship sets of DVDs to customers and business partners.

Depending on the product being used the DVD sets can consist of anything from 3 to 12 separate DVD discs. And they ship 15,000 such sets every month. While the cost of shipping a set of DVDs within the US may be relatively cheap, the cost of shipping on set of DVDs to to a user working in the African jungle maybe as high at several thousand dollars. As well as the actual postage there is the cost of import duties, time to fill out customs forms and get approvals, as well as the actual delivery cost. I was told of one DVD set that involves the monthly rent of a boat and boatman to delivery it along a jungle river!

The total annual postage and delivery cost of DVDs for this company is in the Millions of dollars range, and recent increases in postage rates have meant a dis-proportianate rise in that overhead.

So next time you are considering the cost of your documentation - don't just think about the investment needed to actually create the content - think about what it takes to actually get that information into the hands of all your customers, no matter where they are located.

The evolution of the book.

2010-12-06T10:10:00.002-06:00

Excellent video produced by UK publishers, Hatchette, that reinforces the point that while the technology of the "book" has been, and will continue to be, one of constant evolution, the knowledge and wonder it delivers (i.e. the content) is a constant.

New WIKI book now available

2010-11-21T13:30:00.005-06:00

My latest book "WIKI: Grow Your Own for Fun & Profit" was officially launched at the 2010 XML Conference in Philadelphia on October 13th.

It is now available to order on-line either through the publisher's website, or via Amazon , or Barnes & Noble.com .- eBook Kindle version is also available for just $9.99

WIKI: Grow Your Own for Fun and Profit introduces the concept of wikis, and show why they are becoming the must-have communications and collaboration technology for businesses of any size.
The book will also include several case studies highlighting the ways that various companies are using wikis to solve differing business and communications issues, and the resulting benefits in terms of both efficiency and customer satisfaction.
Looking for a way to increase team collaboration, manage your company’s knowledge? Do you need a way to manage projects with customers or suppliers outside your company firewall? Would you like your customers to provide feedback on the information you publish? Then a wiki might be just what you are looking for.
Perhaps you have already decided that you should use a wiki, but are not sure how to go about it. Maybe you have a wiki but would like to encourage more people to use it. Or you would just like to learn more about the practical applications for this fast growing technology.
Then this is the book for you.

The Global Language - A Preview

2010-09-28T18:17:00.004-05:00

Perhaps the greatest advantage offered by the Internet and the World Wide Web today is the fact that it is truly “world wide,” and opens up an unprecedented international marketplace for the delivery of goods and services. Small companies can now sell into marketplaces never dreamed of before, while large multinational companies can streamline their internal communications; and cross-border and cross-cultural cooperation has become a reality.

However the global marketplace also raises a fundamental issue – that of global communications.

Global communication raises the idea of a common language that will easily be understood by all who use the information being delivered. It is still a common misconception that the dominant language on the web is English and is the de-facto language of business. This stems from the fact that the early days of internet growth was primarily from within the United States, but was quickly overtaken by other cultures, especially in Asia and the Pacific Rim.

While English is still the most popular language on the web[1] (only just – Chinese is close behind) it represents only 42% of all websites. On a global scale English is also in decline as a spoken language. The spoken language with the largest numbers of users is Chinese. As a written language it relies not on abstract symbols (letters), but on ideograms – pictorial representations of ideas. Perhaps this is where the answer to a global language lies. In pictures.

Scott McCloud, a leading theoretician on using graphics to communicate points out[2] that “pictures are received information (they) need no formal education to ‘get the message.’ – The message is instantaneous. Writing is perceived, it takes time and specialized knowledge to decode the abstract symbols of language.”

In the 21^st Century it may be that visual iconography will finally help us realize a form of universal communication.

..... The above is the opening to an article on using graphics, symbols and icons in technical communications that I have just completed for the STC's INTERCOM magazine. - Look out for the full article in the December issue.

[1] http://www.internetworldstats.com/stats7.htm

[2] McCloud, Scott – “Understanding Comics” – Kitchen Sink (1993)

New Book now available for Pre-Order

2010-09-20T16:20:00.002-05:00

My latest book "WIKI: Grow Your Own for Fun & Profit" is written, edited, proofed, designed and off at the printers.

It will officially be launched at the 2010 XML Conference in Philadelphia on October 13th. But you can NOW PRE-ORDER your copy at a discount from Barnes & Noble.com.

WIKI: Grow Your Own for Fun and Profit introduces the concept of wikis, and shows why they are becoming the must-have communications and collaboration technology for businesses of any size.

The book will also include several case studies highlighting the ways that various companies are using wikis to solve differing business and communications issues, and the resulting benefits in terms of both efficiency and customer satisfaction.

Looking for a way to increase team collaboration, manage your company’s knowledge? Do you need a way to manage projects with customers or suppliers outside your company firewall? Would you like your customers to provide feedback on the information you publish? Then a wiki might be just what you are looking for.

Perhaps you have already decided that you should use a wiki, but are not sure how to go about it. Maybe you have a wiki but would like to encourage more people to use it. Or you would just like to learn more about the practical applications for this fast growing technology.

Then this is the book for you.

An early reader review has already described the book as "Indispensable for people who want to get a wiki going."

There is also a dedicated FaceBook page for the book where you can sign on to get all the latest news and happenings, as well as discuss the ideas and techniques covered.

There's More to eBooks Than Words

2010-07-12T16:52:00.003-05:00

“It’s all about the content.”

This simple, yet insightful, comment by leading publishing consultant, Ann Rockley, during a recent webinar on “Exactly What Not to do When Making the Move from Print Publishing to New Media,” (made me think about the many discussions I’ve had, and the many articles I’ve read, about the so-called digital publishing revolution.

I came to the realization that most of us are missing one vital component of this new opportunity. It seems that no matter how much we talk about the changes in process from print to eBooks, we still aren’t giving enough consideration to ways to add value to the content itself. Even when we create and repurpose content, using either traditional serial, or modern modular approaches, we are still, for the most part, delivering content that is not really taking advantage of the fact that the delivery platform (be it Kindle, iPad, or who knows what in the future) is digital.

For all the talk, we are still mainly focused on delivering text.

- Read the rest in my latest article for THE CONTENT WRANGLER web site - "There's More to eBooks Than Words."

Are you an "Awesome Dude"?

2010-07-10T16:47:00.004-05:00

I just spotted this message posted by one of my nieces to her FaceBook account the other day:

[name] finally has picture messaging on her Nokia N900 thanks to an awesome dude and his step by step youtube video!!

A seemingly simple message, but one that made me stop and think. I've written, and spoken a lot over the last year of so about the way that the digital generation access and assimilate information (a subject I'll be revisiting at this year's LavaCon), and also held forth on my view that as Technical Communicators we should be embracing and working with new media.

Here is a perfect example of that convergence. Rather than use the manufacturers, instructions, or look for an answer on their web-site, or on-line help, my niece turned to the internet and the wider online community.

Her answer came not from Nokia, but from some "awesome dude" on YouTube.

What are you doing to make sure that you as a technical communicator can be the next "awesome dude"?

LavaCon 2010

2010-06-29T12:08:00.004-05:00

I will be presenting two sessions at this year's LavaCon conference in San Diego from Sept 29 to Oct 2nd.

Is Print Dead? Digital Content for the Next Generation

The new generation of customers and technical communicators look at information design and collaboration in a totally new way. The book paradigm and things like Tables of Contents and Indexes are alien to them. So how do we prepare? One way to watch our kids do their homework and we learn from them. This session will take a look at why the print page based model we are all so used to is broken, and puts forward some ideas on how we should be thinking about information design for the digital generation.

And

The Case for a Chief Content Officer

Every company does five things, develop a product or service, tell people about it, sell it, collect money for it, and write about it. The first four activities are usually the responsibility of either a VP or CXO level executive, while the fifth is virtually ignored. This presentation will talk about how to identify, organize, manage and leverage a company’s biggest hidden asset — its content — at a strategic level.

Click on either title to vote for the session, or to leave comments and feedback.

Technical Communication As Story Telling

2010-06-29T11:16:00.003-05:00

Over on his "I'd Rather Be Writing" blog, Tom Johnson, has taken my idea of Tech Comm as storytelling, and expanded on it an excellent post, that I highly recommend.

In particular I like these two ideas on the practicalities of applying story telling techniques to technical documentation:

THE ELEMENT OF CHANGE

In a good story, the resolution always brings about some type of change, or comes about because of change. If you listen to stories on The Moth podcast (a storytelling podcast), you’ll constantly hear this element of change near the end of each story. For a story to feel meaningful, the protagonist always changes as a result of the conflict. Without this element of change, the story feels flat.

In technical documentation, achieving that element of change is difficult. In almost all technical documentation, the reader is the protagonist, since our point of view is second person (“you”). You (the reader) have a problem. ..... Through the help topic’s steps and information, you find a solution that solves your problem. Hooray, you’re much happier and complete now. That’s the basic transformation.

And..

FOCUSING ON THE PROBLEM

A problem of some kind usually drives and gives rise to the story. But isn’t every help topic by default the answer to some problem? And aren’t users coming to the help content with a problem already in mind? Do we need to explicitly supply the problem, since it’s already apparent in the user’s mind?

Yes, your protagonist already has a problem. That problem is what is fueling his or her path through the help. But it can still be helpful to state the problem explicitly so that users can connect their problem to the solution you describe.

In many ways the examples and ideas that Tom cites, also feedback to my earlier post on Applying the 10 Commandments of Storytelling to Technical Documentation.

It's great to see these ideas being picked up and expanded upon.

Print or Digital ? - Using Augmented Reality to bridge the gap.

2010-06-22T11:31:00.003-05:00

One of the the strangest aspects of all the recent discussions in the mainstream publishing world about the emergence of eBooks seems to be the notion that digital and print are mutually exclusive delivery options.

Nothing can be further than the truth; as we well know in the technical and corporate publishing world, electronic delivery of information is just one delivery option.

But how about combining the two? Print publications augmented by digital content?

Check out this video of a young reader's reaction to a copy of the BBC's science magazine, FOCUS, with augmented reality content.

Think about how effective that would be when used to deliver technical or training materials?

Perhaps Augmented Reality maybe just the thing to bridge that perceived gap between print and digital? Food for thought.

Where's The Manual?

2010-06-18T11:10:00.004-05:00

Over the last couple of days my life in corporate and technical communications seems to have crossed over into my life as both a pop-culture writer, and motor racing fan.

While watching the advance press-screening of TOY STORY 3, I was delighted to discover that a central plot point revolved around the toys using the manual to discover how to effectively reboot Buzz Lightyear via his 'reset' button - of course, as they say, "hilarity ensues."

Then this morning I was pointed in the direction of this amusing video of McLaren Formula One team drivers, Jenson Button and Lewis Hamilton, both World Champions, trying to build one of their race cars without the aid of their team. The plaintive cry of "Where's the manual?" made me smile.

But as much fun as it is to hear "manuals" used and talked about like this, it made me think about a more serious take.

I still keep hearing people in the technical communications industry say they aren't valued, that what they do has no place in a hi-tech digital world. Well it doesn't come much more hi-tech than Formula One, or digital than Pixar, but still the idea of, and need for, a "manual" is paramount.

In both cases, the toys, and the drivers, wanted to know how to do something.

And that's where the future of technical communications lies. It doesn't matter what form the "manual" may be, now or in the future; we have the skills to provide the best answers to the question "How?"

Now, that's real value...

Just ask Buzz or the McLaren F1 team.

What's Your Frame of Reference?

2010-06-07T14:34:00.002-05:00

I spent a large part of this last weekend attending various sessions at the annual "It's My Heart" conference on Congenital Heart Defects (my youngest daughter is a CHD survivor - and she and her mother are very active in trying to raise CHD awareness).

As the majority of the sessions were hosted by various members of the medical profession, I expected them to be freely peppered with jargon (see my last post), but what really caught my attention was the frequent referencing of names and research to an audience, that, no matter how educated they had made themselves on various aspects of CHD, could not follow the point being made.

This group of medical professionals knew they would be speaking to an audience of lay-people whose own experiences lay outside those of the medical staff they interact with on a day-to-day basis; but no adjustment was made to accommodate that.

The first rule of any sort of communication is know your audience and adjust as necessary. While the various surgeons did explain a lot of technical information, references to other supporting material and research remained obscure.

This made me think about my own techniques when presenting. My public speaking tends to fall into two camps, the corporate communications world, and the creative side of pop-culture. I know I often make pop-culture references when I talk about corporate communications, but now I wonder am I assuming too much that my audience will understand them?

Adjusting for the audience is not just about vocabulary and jargon, it's also about adjusting your own frame of reference.

Enter The Jargon!!

2010-05-20T10:31:00.004-05:00

Whenever I am teaching a course on the philosophy and techniques of writing using Plain Language, or a Controlled language, such as Simplified Technical English, one of the "rules" that I most often quote and emphasize is:

"Avoid the use of industry jargon."

It seems a logical and obvious piece of advice, and not one I'd given much additional thought to, until asked the question, "what do you mean by jargon?" My immediate answer was "terms used exclusively within your industry that wouldn't be understood by people outside of it."

But over the last few weeks I've begun to question my own answer.

Webster's dictionary defines jargon as " the technical terminology or characteristic idiom of a special activity or group," which seems to fit with my original answer. But how do you define that group, and where are its boundaries? When does jargon become acceptable?

Think about the number of technical terms that are now part of everyday conversation - 'download,' 'upgrade,' etc. Do they still count as computer industry jargon?

What started me down this line of thought was working on my current book project about Wikis. While at the recent STC Summit in Dallas I used the word "wiki" without a second thought. It's a word well understood in that community, and I guess it could be considered industry jargon.

But outside of that group I find that when I talk about my book to a much broader audience there is a high percentage of people who know what a wiki is and can explain it quite succinctly. There are also still a sizable proportion who give me a blank stare until I say 'Wikipedia." A few days ago a writer friend of mine posted on his blog that he had being doing some research on "the wiki." He, of course, meant he had been using Wikipedia, just one (extreme) example of a wiki implementation.

But his use of a generic term for the technology made me wonder, is the word wiki moving away from jargon to becoming mainstream. If it is - what does this mean for professional communicators trying to avoid the use of jargon. Is what we consider jargon a label that is only proportional to the size of the community that accepts and understands a specific definition of a word? The smaller the community, the higher a word's potential "jargon" rating?

New Book Project: THE CONTENT POOL

2010-05-18T11:04:00.003-05:00

Contracts are signed so can now announce that I will be writing another book for XML Press - "THE CONTENT POOL" will be published in 2011.

So what is "THE CONTENT POOL" about?

THE CONTENT POOL
How to Identify, Organize, Manage, and Leverage Your Company's Largest Hidden Asset.

Every company, no matter what industry they are in, or product or service they create, do four basic things. Offer something for sale, sell it, collect the money for it and create content about what they do. Product development, Marketing, Sales and Finance are all recognized as essential to the organization and are often reflected by VP or CXO level responsibility, yet a company's content, which contains all of its intellectual property, is often overlooked. Whether they realize it or not every company's secondary role is that of being a publisher. This book will aim to place content creation, management and distribution on a par with other core strategic business activities.

Identifying, organizing, managing and leveraging your content properly can make you money.

The book will take a look at:
- Why every company is a publisher.
- What content do you produce now and how do you use it.
- Identifying the audience, today and in the future.
- What about the language you use - is it costing you money or even making you legally liable?
- Content development silos - gain through collaboration.
- How Consistency saves you money.
- Where are your pain points?
- Styes and Standards
- Rewrite and reuse.
- It's about answers not the documentation.
- Your customers will add value to your content
- Technology comes last.
- Your content can be a revenue source.
- Good content wins customers
- Helpful content reduces support costs.
- Develop a Content Strategy.

The book will conclude with - The Case for having a CCO (Chief Content Officer).

STC 2010 - A short walk from history.

2010-05-07T09:24:00.006-05:00

For the first time in many years I wasn't chained to a vendors booth during the STC Summit, which meant as well as presenting, I could actually take time to sit in on many other sessions, and have lengthy hallway (and coffee shop) conversations.

What struck me about this year's Summit was how upbeat it felt in contrast to recent years. There was, at least to me, a definite feeling that the STC, and the industry itself, had weathered a crisis and was heading in the right direction. Yes there are still challenges to face, but there is definite light at the end of the tunnel.

There was less talk this year about jumping on to the latest production technology fad, and a lot more about considering our audience and answering their needs. As Anne Gentle put it during one panel, "it's about answers, not about documentation."

[Although one technology fad that was pretty much a constant - was the use of Twitter - used as both a communications tool and a way to post notes and ideas from sessions it added another valuable layer to the conference experience.]

I was also pleased to see that on the whole the attendees realized that as the industry is changing, so they need to. There were very few with the crossed-arms defensive "I am a technical writer" posture; most of the people I spoke to, and the audiences in the sessions I attended, realized that this is the perfect time to make yourself even more valuable by adding new skills and re-evaluating and realigning your role. Be it Information Architect, Community Manager, User Experience Designer, Multi-Media Producer, or something else, there is great opportunity out there for skilled and open minded technical communicators.

Each time I visited the expo floor it seemed busy, and all the vendors I spoke to were very happy with both the constant traffic flow and the questions they were being asked.

When I set out for the conference I had delusions that I would get an hour or so each evening to sit in my hotel room and write - it didn't happen. Literally from breakfast at 7:00am to crashing at 11:00pm each night, it was pretty much constant conversation and learning. All the presentations I attended were excellent and the two panels I participated in were great fun. I know the panel format was a bit of an experiment this year, but I hope that it returns for future conferences.

The conference was held at the Hyatt Regency in Dallas, and was just a couple of blocks from the infamous Dealy Plaza, site of the Kennedy assassination. (in fact I could see the plaza from my hotel room - see photo above.) Hence my title about being a short walk from history. But I also believe that the profession itself is now also a short walk away from its own history. It faced a crisis over the last 12 months that it has endured and come through, and we are now on the first steps of a new direction. What direction that new history takes, will be up to us as a profession, and us as individuals, as to how we adapt and embrace the new challenges awaiting us.

Wow this looks cool - but hang on a minute...

2010-04-01T11:08:00.004-05:00

The first time I saw this video from the folks at TIME Inc. on the possible future of their glossy magazines (in this case Sports Illustrated), I thought - Wow, they get it. Someone has at last seen the real potential of using digital content.

But the more I watched it, two things suddenly occurred to me.

While the flashy interface may look cool, it is still very much a paper based paradigm with a page-based sensibility. - Now I accept that jumping straight from physical paper limitations to the theoretical infinite canvas of a digital world may not be acceptable for the consumer market, and this sort of screen bounded design maybe the best solution to manage that transition.
The text is still being considered as a design feature and a lump of fixed content. There doesn't appear to be any mark-up used to make the text intelligent. Where are the hyper-links in the articles? Consider an SI article that on the mention of an athlete's or team's name lets you pull up a library of photos and past articles from the SI archive. Or links to apps that let you build your own performance statistics. How about a link to a virtual tour of a stadium? Or an audio clip of a classic piece of commentary.? Why not the ability to search the text, and order your results the way you want them?

While the surface results of this mock-up look amazing, underneath it is still bound in many ways by thinking of the publication as the product and not the delivery of intelligent content as a portal to adding value.

Times They Are A Changin' But Most Publishers Aren't

2010-04-01T11:04:00.002-05:00

A few days ago I saw a job posting from the publishers of my first book, who were looking for an editor for one of their imprints. What caught my eye was that the posting emphasized that the new editor should have experience and skills in using the same software that had been used to produce my book. A book that was published in 1997 – thirteen years ago!
Technology has changed a lot in thirteen years and so has the way that content can be created, handled and made ready for publication. But this publisher is far from being alone in sticking with old processes. My experiences working on other book projects in the last few years have just reinforced my belief that the vast majority of the traditional publishing market still works around a production system designed to do one thing – move paper.

A process that, despite changes in tools, has changed little since the dawn of the printing press.

You can read the rest of my article on using XML in Publishing at THE CONTENT WRANGLER

Writing Technical Comics

2010-03-04T19:32:00.002-06:00

My article on "Writing Technical Comics" was selected as the lead feature article for this month's issue of the STC magazine, INTERCOM.

It is now available as a free download by clicking HERE.

Tech Comm Ts

2010-02-23T11:07:00.003-06:00

You've seen all those t-shirts with fun slogans for programmers, scientists, chemists and virtually every other profession. So why not have a range of fun t-shirts for Technical Communicators?

We've decided to solve that shortage in the market by setting up an online store called Tech Comm Tech T-Shirts.

To start with each design will only be available for a month.

Kicking things off, and available till the end of February is the "I CAN SPELL XML" shirt.

You can get yours at the online store.

Look for more designs over the coming months.

10 Questions You Must Ask Before Implementing a Wiki #10

2010-02-12T17:29:00.001-06:00

Ask yourself and your team the following questions before you start to implement a wiki, and be truthful with the answers.

Think about the issue you are trying to solve, and then see how a wiki might be applied, but remember don’t just focus on the positive, think about the potential down sides too.

10. What sort of controls will I need, if any?
It can be argued that the first rule of wikis is that there isn’t any rules. It is true that wikis function best when they are driven by the community that uses them, but you need to think about a few basics of control before you start. Do you need logins, if so who will authorize those. Will you have some sort of initial structure? What about giving users a ‘sandbox’ area to learn the wiki in? Who can see, read and edit what pages? Who will monitor recent changes and do any necessary roll backs? What’s the philosophy for rolling back content, incorporating comments? You will find that these answers change and evolve along with the wiki, but it is good practice to at least set a baseline.

10 Questions You Must Ask Before Implementing a Wiki #9

2010-02-11T15:03:00.000-06:00

10 Questions You Must Ask Before Implementing a Wiki #8

2010-02-10T17:11:00.000-06:00

Ask yourself and your team the following questions before you start to implement a wiki, and be truthful with the answers.

Think about the issue you are trying to solve, and then see how a wiki might be applied, but remember don’t just focus on the positive, think about the potential down sides too.

8. Where will the wiki be hosted?

The location and hosting of a wiki can be a contentious issue and it is one that needs addressing early. In large organizations the IT group may want to host it (or they may actively be against the idea), in certain circumstances it may be better hosted at a departmental or project team level (and trends seem to indicate that these sort of bottom-up wiki implementations are usually the most successful ones), or even by a third party wiki hosting company outside the firewall.

10 Questions You Must Ask Before Implementing a Wiki #7

2010-02-09T14:52:00.001-06:00

How a Great Story Can Help Your Brand

2010-02-09T14:26:00.004-06:00

Yesterday evening I spent a couple of hours interacting with other local business people and entrepreneurs at this month's Network In Austin event. As usual it was an excellent opportunity to meet and learn about a whole new bunch of local businesses.

In the space of two hours I must have heard about at least a dozen new businesses, what they did, and what they were called. That's a lot of information to take in in a short time.

As I drove home I did a quick mental review to see if I could recall the salient points from each conversation. I managed to recall something about everyone, but what struck me was that the first two businesses that came to mind were the two that had stories attached, and one in particular that had a story attached to the brand name.

The lady who ran the company had told a fun short story of how the company name came from an expression her father used to use a lot.

Brand names with a story behind them stick.

Several years ago I used to write a regular marketing newsletter that included the stories and histories behind some of the most well known brand names. That section was always the most popular part of the newsletter. It gave me the idea of maybe writing a book on the subject - but then I found out that someone had already done it...

And Evan Morris' fun book "From Altoids to Zima" is now one of the most thumbed books on my marketing bookshelf.

There is a story behind most company and brand names. I've worked for companies named after bags of chips, science fiction villains, a historical event, and even one that got it's name from a typo.

Discover your story - work it in to your pitch, put it on the website, and people will remember it, and they will remember you.

10 Questions You Must Ask Before Implementing a Wiki #6

2010-02-08T20:13:00.000-06:00

Ask yourself and your team the following questions before you start to implement a wiki, and be truthful with the answers.

Think about the issue you are trying to solve, and then see how a wiki might be applied, but remember don’t just focus on the positive, think about the potential down sides too.

6. Who will use the wiki in the future?
Of course one of the great things about wikis, and the central theme of this book, is that they foster growth and further collaboration. There are numerous examples of cross pollination of wikis inside organizations as one team sees the benefits that another gain from using a wiki. Before you start even the first wiki, spend some time thinking about areas of potential growth and possible future cross functional collaboration. Make sure you make plans for scalable growth and allow easy access for anyone who may need to contribute, or observe, not just on the initial projects, but on potential future ones as well.

The Week in Wikis - Week #5

2010-02-07T15:53:00.002-06:00

Here's the list of wiki related articles that caught my attention over the last week.

- DoD ‘Wiki’ Increases Technical Collaboration
- Geo-Wiki - Combining wiki with Google Earth
- Wiki technology fuels collaboration, at Ohio State
- The Internet Engineering Task Force has set up a wiki to document which of its standards were successful and why.
- NASA + Wikipedia = OpenLuna - an open source, wiki-based attempt to design a leaner, meaner, public driven moon mission.

As always the full list of all Wiki Week links can be found at http://delicious.com/wikiweek/

10 Questions You Must Ask Before Implementing a Wiki #5

2010-02-05T17:01:00.000-06:00

10 Questions You Must Ask Before Implementing a Wiki #4

2010-02-04T16:48:00.001-06:00

Ask yourself and your team the following questions before you start to implement a wiki, and be truthful with the answers.

Think about the issue you are trying to solve, and then see how a wiki might be applied, but remember don’t just focus on the positive, think about the potential down sides too.

4. Where is the content going to come from?
Meaningful content is the key to any successful wiki, but you need to think about where it is going to come from. While you will most likely be looking for the community to contribute, you will most likely want to seed the wiki. Where is this initial content going to come from, will you need to invest time in creating new content, or will you import existing legacy content from other systems, such as technical documentation, training, policies and procedures or marketing materials?

10 Questions You Must Ask Before Implementing a Wiki #3

2010-02-03T10:41:00.002-06:00

3. What’s the expected return on investment?

One of the first questions asked for any new system is usually a financial return on investment (ROI). With wikis the software could be as low as zero and as high as several thousand dollars for an enterprise solution. The highest cost will be a resource one, so think about your answers to the previous question. The ROI may not be one directly attributable to the wiki itself, but may come from a change in collaboration methodologies and operational
improvements.

Getting over the barriers to wiki adoption

2010-02-03T10:37:00.002-06:00

My latest article on wikis is now up at the Conde Nast Digital ars technica website.

Here's a taster...

As I continue to research and write my upcoming book on wikis, I keep hearing one word over and over again. That word is "BUT" (complete with all-caps), as in, "I would like to use a wiki, BUT…" or "We tried using a wiki, BUT…"

What follows is usually an excuse for why the speaker feels that a wiki isn't a worthwhile tool for collaboration in his or her environment. I use the word "excuse" deliberately, because rarely does anyone articulate an actual business reason, such as a lack of need. When I ask deeper questions, I invariably find that the objection isn't to the wiki technology itself, but instead to the concept of collaborative authoring and a perceived loss of control over the content.

The true business benefits of collaborative knowledge sharing, such as improved productivity, greater efficiencies, removing cross-functional boundaries, enabling customer feedback etc., are often lost to a perceived, and understandable, fear. In the modern workplace, we have traditionally been defined, both in terms of success and hierarchy, based on what we know.

The old saying that knowledge is power has been a true axiom for a very long time, but the first few years of the new century have changed that. Internet culture, especially the social networking phenomenon of the last few years, has made knowledge-sharing the accepted norm outside of the work environment. Today, anyone who has access to an Internet connection has immediate access to a wealth of knowledge at their fingertips, to an extent literally unparalleled at any other time in human history. We expect to be able to use that information, and we expect to be able to contribute to it.

Yet there remains a reluctance to transfer this social behavior into the work environment. The knowledge base is clearly moving away from a select number of individuals towards the community; and companies that embrace the idea of community are becoming the biggest success story of recent years.

You can read the full article HERE.

10 Questions You Must Ask Before Implementing a Wiki #2

2010-02-02T15:34:00.000-06:00

Ask yourself and your team the following questions before you start to implement a wiki, and be truthful with the answers.

Think about the issue you are trying to solve, and then see how a wiki might be applied, but remember don’t just focus on the positive, think about the potential down sides too.

2. How will you measure its success?

The business issue will impact how you measure success, these could be along the lines of percentage of community contributing, number of people registered, number of new articles or comments. Or it could be asking did the wiki reduce the time taken for a particular process; or even analyzing its impact on other systems, such as the reduction in email traffic, or a reduction in number of meetings

Marking Up The Fab Four: Just Imagine What XML Could Do For Your Books

2010-02-02T15:24:00.004-06:00

Just posted over at THE CONTENT WRANGLER is my first article in what is planned to be a series examining how the traditional book industry could benefit from adopting XML.

Here's an extract from the first post ...

When I look at my book (Before They Were Beatles) on the Kindle, or on my iPhone, I am frankly disappointed in it. The reason? eBooks and eBook readers today are little more than simple electronic page turners.

But it doesn’t take a lot of imagination to think what they could be like. My book references lots of early recordings of various incarnations of the group that would become The Beatles – wouldn’t it be great to click on a link and actually hear those recordings, or even compare early versions with later versions recorded at the height of their fame. How about when I mention their encounters with other musicians? It would be cool to be able to click on a name and get a snapshot biography, links to books about them and access their music catalog. How about accessing photographs of 1950s Liverpool street scenes, or being able to tour the Fab Four’s childhood homes?
And it’s not only non-fiction where I see these sort of enhancements, imagine reading your favorite novelist, and when a character mentions a location being able to click through to the Google street view, or when they eat at a nice restaurant being able to access the recipe. Ever wanted to know exactly how to make the type of vodka martini that is best served shaken, not stirred? It could be just a click away.

There is no technical reason why this sort of interactive book couldn’t be done today.

You can read the full article here.

10 Questions You Must Ask Before Implementing a Wiki #1

2010-02-01T17:13:00.003-06:00

Ask yourself and your team the following questions before you start to implement a wiki, and be truthful with the answers.

Think about the issue you are trying to solve, and then see how a wiki might be applied, but remember don’t just focus on the positive, think about the potential down sides too.

What business issue is the wiki being used to resolve?

For any technology implementation to succeed, there needs to be a problem that it is trying to solve, or an operational efficiency to be gained. Think about why you are considering a wiki, do you have examples of wikis being used to address similar issues? Did they work? If so, why?

iPad - Racing Towards Publishing's Future?

2010-01-30T17:26:00.005-06:00

This afternoon I’m sat watching the first major motor race of the 2010 season, the Rolex 24 Hour sports car race at Daytona in Florida. When the race started it was raining, but over the last hour or so the drizzle has stopped and the track started to dry out a bit.

As in any race where the conditions change several drivers choose to come in early and switch their treaded wet weather tires for slick dry weather tires while the track was a little damp. Racing drivers being racing drivers several set off at full throttle back on to a damp track with cold slick tires and promptly spun off, some of them several times. While others balanced the risk with a degree of caution and soon found them selves making rapid progress.

Watching the race unfold over the last hour in changing conditions made me think about this week’s launch of the Apple iPad and the various reactions to it among the digital and technical publishing markets.

There is no doubt that the iPad is a clear sign of changing conditions in the industry. The trick will be how you approach those conditions.

Some will go full out to get to the first corner, by making hasty judgments, rush into new markets without testing, or just repackage existing material without adding any value. I believe that many of these chargers will ‘spin off.’ Some of them will crash and be out of the race, others will work their way back.

Others will take a more cautious approach, feeling out the new conditions, making small adjustments, see how the chargers are doing, watch others make mistakes and learn from them.

Over the last few days I’ve been asked several times what I think about the iPad. I think it’s too early to make a call about doing a ‘pit stop’ to start ‘changing tires.’

At this point I’m not sure what additional value the iPad brings – sure I’ve seen the videos, but I need to see one in action, maybe take a look at what some of the hard chargers are doing, and then maybe I’ll get a better idea of what race strategy we need to peruse to get to the finish line.

This Week in Wikis - Week 4

2010-01-30T16:16:00.002-06:00

Another quite week on the wiki front, but here's a short list of some articles that caught my attention over the last few days.

- Wiki Web Help - "an AJAX-based wiki designed to operate like a CHM viewer"
- EBU's Wiki helps Haiti radio stations
- Wiki vs Professional debate in travcl guide industry.

As always the full list of all Wiki Week links can be found at http://delicious.com/wikiweek/

This Week in Wikis - Week 3

2010-01-24T17:43:00.003-06:00

A shorter list this week, but here is a quick summary of interesting wiki related articles etc. that I came across over the last seven days.

- Atlassian Snags 2009 Elearning! "Best Social Learning Tool" Award.
- MyWiki app of the iPhone
- Appropedia - the 'green" wiki
- Antifeatures Wiki Catalogues Tech Annoyances You Hate

as always a full archive of all Wiki Week links can be found online at http://delicious.com/wikiweek

Video Interview on Using Wikis in Technical Documentation

2010-01-20T08:34:00.004-06:00

I was recently interviewed by Ellis Pratt of Cherryleaf about the use of wikis in technical documentation. It was a fun and wide ranging conversation that lasted about an hour.

Ellis has prepared the following couple of short, 10 minute, extracts from the video interview and posted them on You Tube.

The Augmented Future of Technical Documentation?

2010-01-19T15:04:00.005-06:00

For those of us who have written, or write, technical documentation for hardware, and engineering products, this video of a BMW research project perhaps gives a glimpse of the future.

And BMW are not alone, a quick search online produced videos of several different prototypes of using Augmented Reality for maintenance, service and repair procedures.

This type of development, once again reinforces my message that technical writers need to step up and become technical communicators comfortable with developing content that can be delivered in any media.

Technical documentation is not just about the written word, it is about the communication of ideas and knowledge.

Hello Publishing, Meet the other side of Publishing

2010-01-18T16:53:00.006-06:00

Over at the TeleRead blog, which reports on trends in the growing eBook market, editor Roger Sperberg recently posted a piece entitled "Why Do Publishers Need XML?" in which he thoughtfully examined the advantages that traditional book publishers could benefit from by adopting an XML mark-up.

I won't reiterate his arguments here, most of which I agreed with, and suggest that instead you go read the article.

However one statement really caught my attention, Sperberg's suggestion that book editors should learn XML as part of their job. His statement was that

"...that we (book publishers) can’t exploit (eBooks) until editors understand XML as well as English grammar, and regard metadata as valuable as a plug on Oprah."

At face value a very valid point, but as I read through the article and the various comments attached to it, I suddenly realized there seemed to a complete lack of awareness that those skills already exist within a profession that understands a bit about publishing.

Here's a little extract from my own comments.

"As for asking editors to learn XML, sure they need to be aware of it and its power – but there is a whole profession of people out there who already know about applying XML mark-up to content – the Technical Publications industry. Oh and a lot of them know about XSLT and XSL-FO too, and are skilled in the tools that use these standards.

And believe you me, for people who have spent years tagging things like aircraft manuals and software user guides, tagging a trade mass market book is not too great of a challenge."

It is often said that traditional book publishing is dying, and a large part of that is because traditional publishers still see the physical book as the product, and not the content. But today content is king, and we need to make that content available across all platforms, and that means mark-up.

Does the salvation of the book publishing industry reside in the world of technical and business publishing? - It just might...

A short commercial...

2010-01-18T16:40:00.001-06:00

Join me at 1:00pm ET on Wednesday (Jan 20th) when I present a live webinar on 'What Technical Communications Can Learn From The Comics."

This Week in Wikis - Week 2

2010-01-17T16:58:00.003-06:00

Another round up of interesting links and articles about wikis found while I continue to work on my upcoming book "WIKI: Grow Your Own for Fun and Profit."

Week 2

And a reminder that all the wiki links can always be found at http://delicious.com/wikiweek.

English as She is Spoken - it can be difficult at times.

2010-01-10T10:29:00.002-06:00

Earlier today, The Content Wrangler, Scott Abel, posted the following on his FaceBook page:

[English Lesson du jour] Leonard Lunsford says the letter combination "ough" can be pronounced 9 different ways. The following sentence contains them all: "A rough-coated, dough-faced, thoughtful ploughman strode through the streets of Scarborough; after falling into a slough, he coughed and hiccoughed."

This sort of thing is a perfect example of why we shouldn't assume everyone in your intended audience understands the subtleties and nuances of the English language - particularly important if you are creating technical or business content for an audience who are not native English speakers.

As I mentioned to Scott - I will definitely be using this as an example in the Simplified Technical English training courses I run from now on.

This Week in Wikis - Week 1

2010-01-09T15:56:00.002-06:00

Welcome to a new feature on THE CONTENT POOL, "This Week in Wikis." - As I continue to work on my upcoming book "WIKI: Grow Your Own For Fun and Profit" I am reading and bookmarking numerous articles and online mentions of wikis, wiki tools and examples of wiki usage.

So I thought it might be useful each week to share a selection of wiki related articles I came across over the previous seven days.

Here's this week's selection:
- Wired's "How-To" Wiki
- CarbonCopyPRO Introduces New "Wiki" Marketing Platform,
- MobileRead Wiki on eBook technology
- Wiki on research for librarians
- Improved wiki usage in 2010
- How Non-Profits Are Using Wikis
- Wikipedia:Manual of Style

All the "This Week In Wikis" links will be archived, and available, at http://delicious.com/wikiweek

Comics in Corporate Communications

2010-01-09T14:55:00.002-06:00

Is there a place for comics in corporate communications? I certainly think so, and have long been a vocal proponent of using comics graphic and story telling techniques in the business world.

Recently Scott Abel, industry leading consultant and blogger, offered me the opportunity to write about the subject on his CONTENT WRANGLER blog.

My two page article Comics Can Make You A Better Communicator is now up, and you can check it out simply by clicking HERE.

The GHOST MAP and THE SOCIAL WEB

2009-12-11T15:48:00.005-06:00

Over the last few weeks I've been reading a fascinating book entitled THE GHOST MAP by Steven Johnson, that details the story behind the 1854 cholera outbreak in London and the efforts of a few men, including the physician Dr. John Snow, to isolate the cause.

Dr. Snow is perhaps most celebrated for developing the titular "Ghost Map" that (and this is simplifying the process) helped form a visual correlation between the number of deaths and the proximity of the contaminated water pump that turned out to be the root cause.

It's a fascinating book for anyone interested in social sciences, history, biology, and communication. A large part of the story discusses how Snow culled information from a variety of apparently disparate sources, some written, some verbal, and his own observations and bought them together to develop one of the most celebrated examples of technical communication and visual design of the modern age.

But the book itself has one great failing - it doesn't include a copy of the map! You know the map that is referenced in the title of the book? The map that has a whole chapter to it and to which the author constantly refers. A map that is in the public domain and widely available on the net. Yes THIS map.

Click HERE for a larger high resolution version of the map.

Here is a great example of setting up a reader / user expectation and failing to meet it. The quality of the content in this book was excellent, yet the one thing I will remember most (and obviously decided to blog about) was that single point of failure.

So how does this relate to corporate communications - simply put - make sure that you deliver the content you promise - even if it's an implied promise. And titles are the first place you set up expectations of what's to follow. Make sure you deliver.

So to make sure I deliver on my promise, what does the Ghost Map have to do with the Social Web? In the later two chapters Johnson goes on to discuss the impact of Snow's work on science in general and the use of cartography in mapping social trends.

In that discussion on maps he makes the following observation:

"The amateurs are producing the most interesting work, precisely because they have the most textured, granular experience of their community."

An astute observation and not one that just applies to cartography projects, - it also applies to the changing face of corporate communications and social media. The day of the 'experts' being the sole trusted source of information. As Don Tappscott & Anthony Williams put it in their book Wikinomics:

"There are always more smart people outside your enterprise boundaries than there are inside."

In London in 1854 the experts inside the organization, i.e. the Government, were convinced it was the mythical 'miasma' that was killing people. It took informed 'amateurs' to identify the root cause and develop the documentation to prove their case.

Any organization today should be listening to, and encouraging, the participation of the smart people outside.

Imagine if Dr. John Snow had access to a wiki, or Twitter?

Confessions of a Mark Up Junkie!

2009-11-23T14:18:00.004-06:00

Hello my name is Alan, and I love tagging things.

It has been 15 minutes since I last tagged some text.

There I’ve said it.

A few days ago I came to the realization that I’m a tagging and mark-up junkie. I do it almost everyday, and I do it without thinking about it. I also never thought about the effect my tagging habit had on others, until a few days age when my wife complained about it.

I’ve been tagging for over twenty years now, SGML, XML, HTML, CGM and a multiple variety of typesetting tags and industry specific ones - I’ve used them all. For me tagging is as natural as using the Ctl+ keys to shortcut a menu.

I even used to have a t-shirt that proudly proclaimed:

WILL TAG FOR BEER

But it's time I stopped assuming that others want to join me in this behavior.

What bought me to this realization?

In preparation for our upcoming house move, we decided to sell some of our books on eBay and my wife offered to help set up the listings. I walked her through the steps to sell an item online and all went well until it came to the part where you need to add an item description of the article.

Without thinking I just started applying 'p' tags a 'b' tags and even a few 'a href=' tags . She stopped and looked at me as is to say "What is all this nonsense?"

The feeling that I was perhaps doing something that may not be understood (or needed) by a large percentage of the population was further compounded by various comments and feedback on my article about "Wikis in the workplace" that was published on Ars Technica last week,

Several of the comments made the point that the biggest obstacle to wiki adoption was the perceived notion that you had to learn mark-up to write in a wiki. Whether this is true or not (and it isn't), the idea is out there.

One comment in particular caught me eye.:

I don't know anyone under 40 who will use a wiki at work. The mark-up language is a deal breaker.

While the comment may have been a little facetious, I take the point. I've written before about how we need to observe the way the next generation accesses information. Those comments made me realize that we should do the same for the way that information is created.

In the article I wrote:

Technology geeks need to realize that many of the ideas, features and functions that get us excited and turn us into early adopters of new technology can intimidate the average user to the point where they will be scared off and not use a solution no matter how beneficial it may be.

Everyone is now used to the simplicity and intuitive look and feel of a simple word processor, be it MS-Word or Google Docs, and many other content creation tools, including most wikis, have also adopted the same approach. This is something we need to remember when we become enthused about a new technology or process.

I guess what I'm saying is that having a tagging habit is fine, (and in some circumstances it is a very valuable skill), but it should be exercised when it's needed. When dealing with your audience, customers and general users don't jump in to showing them how clever you are; think about what will make their lives and project easier.

Don't let the technology and techno-babble get in the way.

==============

As an aside - this is the first post on The Content Pool blog not hand coded with HTML tags but written using the in build rich text editor.

================

Wikis in the workplace: a practical introduction

2009-11-17T11:26:00.003-06:00

When times get tough and belts get tight, one of the first things many companies do is begin casting about for ways increase efficiency and raise per-worker productivity. Many businesses turn to free and open-source tools to meet these needs, and at some point in such discussions someone invariably suggests a wiki for some internal project. But the wiki idea often gets rejected soon after it's floated, typically because wikis are perceived to be insecure, inaccurate, or difficult to use; either that, or someone in the discussion has gone the wiki route before, only to see their wiki languish from lack of interest and participation.

These perceptions and experiences that lead companies to reject wikis are rooted in a common problem: the vast majority of the public has formed 100 percent of their expectations about what a wiki can and should be based on the single example of Wikipedia. Few have ever seen wikis used creatively and successfully in a real-life business context, so even when IT professionals attempt to implement wikis in their own companies they lack real experience and good examples to imitate.

As someone who's currently writing a book on wikis, I've talked at length with a number of different organizations about the wiki's role in their business. In this article, I'll share with you some of what I've learned about wikis in the real-world by taking a case-study approach to describing how and why a handful very different organizations are successfully using wikis. After seeing the kinds of things that are being done with wikis, you might be motivated to give the technology a second look.

Read the rest in my article on the Ars Technica website.

Irony, Thy Name Is Webinar!

2009-11-16T17:03:00.003-06:00

Last Thursday evening, while wearing my WebWorks hat, I was happy to deliver a presentation to the fine folks from the North East Ohio chapter of the STC. The title of my presentation was “Why Publishing Is No Longer The Last Step.”

If you scroll through the slides in the embedded copy of the presentation below, you can see that the main theme I was talking about was feedback and how we should both encourage and embrace user participation in the publication process. In fact one of the points I was making was that feedback, user participation and collaborative authoring, while they may all be current buzz words, aren’t anything new. They have been a part of the publishing process for as long as we have been telling stories. It’s just that the technology has changed. In fact it could be argued that modern technology is an enabler that allows us to capture and process feedback even quicker.

Why Publishing Is No Longer The Last Step

View more presentations from WebWorks .

BUT…

When I got home my wife asked how the webinar had gone, and I had to admit that I wasn’t 100% sure. The reason for my lack of certainty? Missing feedback.

Yes a few people had asked questions, and I had received a nice round of applause at the end of my presentation, but delivering the presentation over a combination of WebEx and phone meant I had no visual feedback. I didn’t now if silence meant that people were enthralled, bored, or had all snuck off to the pub!

Anyone who has seen me present will know I like to walk around. I talk with my hands a lot, gesticulate, point. I also like to try and engage the audience, ask questions, crack stupid jokes and make the occasional pun. But perhaps the biggest part of presenting for me, and the main reason I enjoy doing it, is being able to interact and engage with individuals in the audience.

Visual communication and body language provide essential feedback, and in this instance using enabling technology robbed the experience of one of its most vital layers of communication.

Virtual meeting tools and conference calls can be great cost savers and allow events to happen that otherwise might not occur – but even in today’s social network obsessed, web driven world, nothing beats being face to face with a real live person.

Technology should enable conversation, not get in its way.

Working Out With On-Line Help

2009-10-23T09:39:00.006-05:00

For my birthday last month my family decided to buy me the Beatles Rock Band video game, an appropriate gift given my long standing interest with in the Fab Four. But I'm not really a game player and didn't have a game system, so we also decided to purchase a Nintendo Wii and the Wii Fit package to go along with the present.

While I really enjoy the Beatles Rock band, I have become somewhat addicted to the Wii Fit (with positive results on my overall health and posture), and feel like I'm missing something if I don't spend at least a few minutes each day doing at least a few of the exercises.

While working out one morning last week, I had a revelation of the Technical Documentation kind - I suddenly realized that I was in fact working out using what amounted to the Wii Fit's on-line help system.

There is nothing that we would label as traditional on-line help, no Help menu item, no F1 button to press and no self contained documentation - but it has Help all the same.

When you start a new exercise the virtual trainer immediately gives you a demo of the exercise. But just that once, after that it' an option available at the start if you want to refresh your memory.

And note how the Wii Fit uses a simple star system to give you feedback on how well you have done that task in the past - a simple, effective and intuitive feedback loop.

Once you start working on an exercise or task the trainer shows you the moves but also adds step by step instructions with using visual (movement and graphics), audio (voice) and text (on screen instructions).

I have also noticed that as you get better at a task and move up the levels, it makes assumptions on skill level and delivers less basic information. i.e it tracks your usage of the system.

What I am getting is the correct information to complete a task at the point I need it.

I do not have to go find Help on how to do something - the Help finds me as I do a specific task.

As I mentioned in an earlier post, watching my teenage daughter do her homework made me think about the way we need to redesign content structure, so my introduction to video games has made me rethink the way we should be delivering on-line assistance.

Why are we once again force fitting the book paradigm into software assistance and electronic delivery.?Integrated context sensitive help shouldn't just mean that I get a "topic" or "Chapter" when I hit the F1 key - it should mean that the software delivers the information I need at the point I need it based on what I'm doing and how many times I've done it before.

(Apologies for the quality of the photos - took them this morning with my iPhone after I thought about doing this blog post.)

Missing one small (but vital) step

2009-10-07T08:31:00.004-05:00

As anyone who has heard me speak recently will be aware, I'm a big fan of providing minimalist documentation that helps answer the basic question - "HOW?"

How do I make this work?
How do I connect this?
How do I complete this task?

But when I say minimalist, I don't mean badly designed or written - in fact I would argue that the sort of documentation I advocate needs to be better written and designed than the traditional 'owners manual' approach.

In a recent tweet, well known industry consultant, Scott Abel posted

Most people don't want a user manual; they want usable, managable instructions for the task they are doing.

I totally agree.

I often cite a slim 16 page booklet that I received as part of a network router package as one of the best designed pieces of documentation I have ever used as it combines, good use of language with color, simplified clear illustrations and even the physical design of the booklet to quickly and simply answer the question of 'How do I connect this thing up and get my wireless network running?'

Then last night I ended up installing a different wireless router from another manufacturer, which on the surface appeared to be taking a similar, minimal documentation route, but with not quite the same results.

This new router was shipped with no printed documentation, just a CD in a paper sleeve with the words "Start Here" emblazoned on the sleeve.

Once installed a couple of clicks opened up the installation guide - a short, well illustrated, 5 page document.

Looking good so far - but then I scanned down to read the instructions, and saw this.

1. TURN OFF YOUR COMPUTER.

mmmm - see the problem?

You only provide instructions as a PDF on a CD and the first thing you ask me to do is to turn off the device I use to read those instructions. - Not so clever.

The inclusion of another small, but vital, instruction step saying

1. PRINT OUT THIS DOCUMENT

could solve that usability issue.

So think about this - if you are going to produce a minimal documentation set - then at least think about how, and where it is going to be used.

Getting Started type guides will probably always be best as a printed document, which could be anything from a single sheet checklist to a small booklet. But remember you need to apply more thought about design, graphics, language, and usability.

Round Tripping - Myth or Promise?

2009-09-30T16:04:00.004-05:00

As I mentioned in a previous post, later in October I will be taking part in the WikiFest panel as part of this year's Wiki Symposium in Orlando.

As a small taster for those who can't join us (but if you are free that week, I encourage you to make the trip to Florida), here's the brief presentation description I submitted:

Round Tripping – The Holy Grail of Documentation Wikis – Myth or Promise?

More and more companies are using the wiki platform to publish their product and design documentation online. One of the main attractions of taking this approach is the hope that the documentation users will both comment on, and contribute to, the documentation set. In other words that the companies will move from developing documentation based on theory to documentation based on the collective experience of the community. But how do you manage that user generated content? Many are looking towards a solution that will automate the integration of feedback into their source content. This presentation will look at if that goal is feasible, manageable, or even desirable.

Panel Picking Time for SXSWi

2009-08-31T11:25:00.003-05:00

Time is running out to vote for the panels and topics you would like to see discussed at next years SXSW Interactive Conference in Austin, TX.

SXSW Interactive features five days of compelling presentations from the brightest minds in emerging technology, scores of exciting networking events hosted by industry leaders and an unbeatable line up of special programs showcasing the best new websites, video games and startup ideas the community has to offer.

I have a couple of panels up for consideration and if you haven't yet voted, I would appreciate a "thumbs up."

Wikis are Wonderful - or Are They? - Corporate wikis are not wikipedia, but are they of any use? The adoption of wiki technology in companies and organizations of all sizes is growing fast; but is it hype, or are there real benefits? The panel will discuss the use of wikis, when they work, and when they don’t.

Spandex and Software: Can Comics Get You To Read The Manuals? - Google Chrome wasn’t the first product to be accompanied by documentation in the form of a comic book. Sequential art based messaging is everywhere, and has a long history. In today’s more visually literate society is the humble comic book placed to be the next big thing in user docs?

And while you are visiting the panel picker, here's a few more panels that I'd recommend checking out and voting for.

Sarah O' Keefe on "Will User-Generated Content Wipe Out Technical Writers?"

Rahel Anne Bailie on Greening Your Content: Reduce, Reuse, Recycle."

Brenda Huettner on "All About Audience: Improving User Experience."

Charlene Kingston on "Designing Projects That Change User Behavior," and "Reach Your Diverse Community With A Persona Strategy."

Warbling About Wikis

2009-08-19T13:15:00.005-05:00

"You know you should really do that using a wiki," seems to becoming a regular part of my daily conversations. In recent weeks I know I've used it at:

- a social event related to my wife's work when someone was describing a public outreach program they had recently put on;
- a friend's book-signing where I fell into conversation about the usefulness of social networks and community collaboration;
- a science fiction convention during a conversation with a fellow writer about a research project he is part way through.
- a conversation with the CEO of a niche publishing company about using a wiki to connect his existing community of loyal readers.

It's perhaps only natural as I start to write the first few chapters of my upcoming book on the subject, "WIKI: Grow Your Own For Fun and Profit," that the concepts, technology, and practical application of wikis should be fresh in my mind; but what I am starting to notice is just how far reaching the application of wikis could, and should, be.

Wikis are far more than online encyclopedias, or a new way to deliver documentation.
Wikis can also be:
- Project management tools
- Forums for community conversation
- Knowledge capture tools
and much, much more.

In fact when you think about the ways a wiki can be used they can even replace the two most used corporate software applications - email and word-processors.

In October I'll be taking some of this wiki conversation and discussion on the road when I present a session at the WikiFest portion of WikiSym, the 5th International Symposium on Wikis.

I also have a panel on Wikis up for possible inclusion in next year's SXSW Interactive festival. If you would like to be part of that discussion, please head over to the SXSWi "Panel Picker" and give the proposal a "thumbs up" vote.

Is Social Media a Fad? Or Essential to your Business?

2009-08-18T13:40:00.003-05:00

Watch this and then decide if you should be spending your marketing budget and hours on SEO optimization of your website and search based ad-word campaigns, or on building a community using Social Networks?

Rockets and Notebooks

2009-07-10T10:51:00.005-05:00

As I mentioned over on my personal blog recently, I have been doing a lot of research into the history of the space program, and a few weekends ago took a trip to the New Mexico Space Museum. While I was there I got chatting to one of the museum volunteers who had worked in the astronauts’ office during the Apollo days. During the conversation he offered the observation that:
“There were things they did back then that we can’t do today.”

This reminded me of a conversation I’d had many years ago while visiting one of the NASA facilities where an engineer had told me that even though the Saturn V rockets on display at the Cape Kennedy launch site in Florida and the Johnson Space Center in Houston, TX (below) were fully functional, they could never be put back into service as no-one knows how to operate them. As the engineers from the Apollo projects dispersed or died off, and the focus shifted to Shuttle operations, the institutional knowledge needed to launch a Saturn V disappeared.

Recounting this story a few days ago prompted another memory. Several years ago, the consulting company I was working for was engaged to help identify just such a loss of institutional knowledge. During our time at the company we discovered that a tradition had developed among the people who worked on the assembly line to keep a small note-book in their overalls pocket. These notebooks were used to write down workaround steps, or take notations on how to improve the efficiency of the assembly process. Many of the notebooks had photocopies of pages from the company official assembly manuals pasted in with notations added. We also found out that the people with the longest service could assemble the product in about half the time the official process said it would take. The increase in efficiency was due to a combination of experience, and the tricks and short cuts they had written in those notebooks. The real problem came when the longest serving employees retired or moved on they took their notebooks with them. The institutional knowledge was lost. Each new person employed on the assembly process would start from zero with the official procedures and have to relearn all the tricks that their predecessor had developed.

Because the existence of the notebooks was never officially acknowledged, they were never included in any part of the company’s knowledge capture procedures. Our recommendation was to engage the people in the company who had the best skills for interviewing subject matter experts – the technical documentation group. From that point on a monthly review session was held where a technical writer would sit down with the assembly team and take notes on what the engineers had written down in their personal note books over the previous four weeks.

In fact in today’s economy where turnover of staff is high and a lot of valuable information is lost during layoffs etc., this is a great opportunity for a Technical Documentation team to showcase how their talents can be used and the real value they can bring to a company.

If someone who held a technical role is leaving the company, for whatever reason, don’t just conduct an exit interview with the HR department, but have them sit down with a technical communicator who is good at interviewing subject matter experts. Do a proper debrief and capture not only their notes, but the inherent knowledge and process tricks that are in their heads too.

Perhaps if NASA had done this, we might still be able to fly those Saturn Vs.

It's STC not STW

2009-06-22T12:38:00.003-05:00

There’s been a lot written lately about the financial and operational crisis that the Society of Technical Communicators is facing.

A lot of people have posted some great ideas on Twitter (Identified by the #stcorg hashtag), and bloggers such as Sarah O’Keefe and Tom Johnson have outlined several ideas and observations that I agree with, and don’t intend to repeat here.

However there is an aspect of this institutional crisis that I believe needs a little more exposure, and one I’ve raised during several recent presentations at different regional STC events.

The third letter in our professional organization is C. C for communicators. It isn’t W for writers, yet that society is overwhelming sold to technical writers, its publications are aimed at writers, and not surprisingly the vast majority of its members are writers.

But what about the other “technical communicators”? Where are the technical illustrators, the animators, the graphic designers, the video producers, the script writers, the podcasters, etc.?

When I’ve mentioned this before the answer I’ve invariably received is “Oh we have SIGs for them.” – Special Interest Groups – really?

They aren’t a marginalized “special interest,” they are the future of the industry.

When I joined my first technical publications department in the mid 1980s the ratio of writers to illustrators was 2:1, add in other people who contributed to the production of the technical documentation and the number of writers was actually less than 50% of the total departmental head count.

In the opening decade of the 21^st century when more people receive information visually than ever before a Society of Technical Communicators should be full of people who think, and deliver information, visually.

If the STC is to survive, it needs to attract and embrace the practitioners of the visual arts.

The same goes for those who are as comfortable working in the sound medium too – and the training folks who are developing interactive documentation, and – well the more you think about it the more the list grows.

As a writer, I would be delighted to see the day when the membership of the STC resembles that technical documentation department I joined over 20 years ago – where writers are actually in the minority.

Truth in Marketing is not an Oxymoron

2009-06-17T09:40:00.006-05:00

“I’m a writer; I take the truth and give it scope.”

– Paul Bettany as Geoffrey Chaucer in A Knight’s Tale (2001)

If I have one underlying tenet that I try to live by, it’s to tell the truth. It’s a philosophy I also apply to my writing. Most of my published work to date has been non-fiction, and by its very nature involves a lot of research and fact checking to make sure that what you are presenting is the “truth.”

The problem with doing research based on historical events, and particularly in the case of biography, is that the “truth” is often what the person telling the story believes to be true. For that reason, as much as possible, I try and go back to original sources and documentation. The same thing applies when I’m writing fiction, I always try to stay truthful to the established rules of the fictional world I am working in. With a licensed property that also means doing a lot of research into the facts that other writers have established.

So what has this got to do with corporate communications?

Most of the corporate writing I do these days is marketing communications. From blog posts, to Twitter, white papers, product literature, websites, and press releases. And, as with my other writing, I always try to tell the truth. Sure, as the quote at the start of this post mentions, I sometimes take the truth and give it “scope.” Yes I’m perfectly happy saying that 10% is “double digit growth” or that 51% equates to “most,” or “the majority,” because beneath the spin they are still verifiable facts.

Where I have problems is with marketing spin that uses absolute terms like unique, best-ever, ultimate*, or first. if you want to use those terms, that’s fine – but do some research and some fact checking to make sure that you really are the “first to market”, or that what your product does really is “unique,” and if what you are offering really is the “ultimate,” are you really intending to never improve it.

This is even more important when you are marketing to an audience whose daily job revolves around words and the use of language. Say the wrong thing, use the wrong word and they will go check. If what you claim isn’t true – they will call you out on it. That will undermine every other marketing message you put out.

One perceived falsehood can undermine the credibility of everything else you do.

Oh, and one more little thing that drives me crazy, if in a press release, article, or whatever, you refer to another company by name, or one of their products – make sure you get the names right.

In this day and age, fact checking has never been easier, all it takes is a few clicks of the mouse.

There is no excuse for any marketing material not to tell the truth. Sure your readers may have to read between the lines, or decipher the spin, but the foundation of what you are saying should always be verifiable.

================================

* The misuse of the word “unique” is one of my all time pet-peeves. Every time my wife watches one of those house buying TV shows and I here the presenter talk about a “unique feature” that we’ve seen 100 times before, it makes me want to scream.

5 Ways to Make Executives Love the Publications Department

2009-06-08T13:19:00.003-05:00

“Publications never gets any respect,” is a refrain I’ve heard over and over again during my time in the Technical Communications industry. In fact I’ve even said it myself a few times. The refrain is often followed by, “no one really understands what we do, or the value we provide.” The unfortunate thing is that in a lot of cases these refrains have some justification, but it needn’t be that way.

As an example over the years I’ve visited literally hundreds of publication teams in a variety of companies and industries, but one of my most striking memories is the sheer contrast between two publication departments at a couple of luxury car manufacturers.

At the first company, the documentation department had a nice modern office, in a new campus setting. They had all the latest computers and access to great technology. In the parking lot outside the publications office was a fleet of not only their own cars, but those of their nearest competitor. Any member of the publications team could use any of the cars, in exchange for filling in a small usability report. The publications team were a high profile part of the customer support organization and were considered by the marketing team as part of the product “life style” branding activities.

At the second company, the publications department was in an old hut (in fact it was an old coal bunker) at the back of the factory, far removed from the production line, engineering, or any other function it needed to interact with. Although cars were parked outside, the team had no access to them. They had only a handful of computers and their technology was at least five years behind their competitors. The sole mandate was to produce a small defined set of hardcopy manuals. And that’s all they did.

So why the difference? In short the team at the first company acted like they were part of the company and projected a positive image of their skills. As such they were recognized and rewarded. The team at the second company stuck to the “we are only tech writers,” approach. They were, in many ways, responsible for their own position.

So if you feel that your publications team is “in the coal bunker” – how do you change things so that you get the keys to the luxury cars?

The following presents a basic five point action plan to help you raise the profile of what you do and make your executives love the Publications Department.

1. Realize exactly what it is the Tech Doc team does. - Before you can raise your profile, you need to know what you have to offer. Chances are that most Publications teams have talents and skills that exist no where else in the organization, and I’m not just talking about the ability to write. Also most often the Publications team is the only place in a company where all the company’s intellectual property comes together. Publications isn’t about “producing user manuals,” it’s about managing your organization’s greatest asset - knowledge.

2. Tell a good story. – People react to stories on an instinctive level. It’s easier to remember stories than it is dry facts and figures. Publications is the natural bridge between the end user and the company design, engineering and production teams. Gather stories and tell them – repeatedly. Come up with your own stories that illustrate the importance, frequency and impact of your own work. Develop fun trivia about what Publications does that people will remember and repeat.

3. Offer your services for fun and profit – Develop an in-house user community, not just an external one. Look around for other functions that you could work with or offer your expertise to. Develop an entrepreneurial mind-set and you’ll find opportunities to transform publications from an overhead cost-center into a profitable contributor.

4. Hook an executive sponsor – Find an executive’s pet project that could need some creative input, e.g. a little wordsmithing, or some graphic design work, and get involved. While the work is progressing make sure to bring the executive into your environment, and show off what the publications team can achieve.

5. Change attitudes. – If you go around say “I’m only a tech writer,” or “publications never gets any respect,” then people will believe you and act accordingly. Be aware of what you do, what you can offer and be proud of it. Treat your team (even if it’s only you) as if it was your own business. Build brand awareness, market and promote what you have to offer, and sell yourself, your team and the profession.

Over the coming weeks I’ll take a expand on each of these and provide some examples and suggested strategies.

2009 Conferences - Never mind the quantity, experience the quality.

2009-04-24T15:44:00.004-05:00

In the current economic climate one of the first items that get cut in any budget squeeze is usually travel, and subsequent attendances at industry conferences. But, judging by my experiences at the two industry conferences I’ve attended so far this year, DocTrain West and WritersUA, this is a false economy. Yes attendance was down at both, due to aforementioned budget and travel restraints, but they were two of the best conferences I’ve attended in years.

Simply put, those people who were at the two events, were fully engaged in the conference. The conversations were compelling, interesting, relevant, and thought provoking. The speakers seemed to be of a higher quality and all the presentations were equally worthy of note and attention. The organizers of both conferences had put together excellent sessions with distinct themes. Most of the time I found myself attending one excellent session while at the same time wishing I could have been at a different concurrent session that sounded just as interesting. The most difficult aspect of these two conferences was scheduling your time.

Having spoken to several people who also attended either one, or in some cases both, of these conferences, it seems that I am not alone in these opinions.

So why in a time of economic belt-tightening are the conferences so much better?

Firstly I believe that the majority of people who at the conferences, speakers and attendees alike, most likely had to give a good justification for being there. While you should always have a good reason for attending any conference, having to justify the expense can be a great motivator and help you to determine a real need. Everyone who was there, was there to learn. And if I perceived one over riding sentiment from both conferences, it was that they were unparalleled opportunities to learn from industry experts and peers alike.

It was noticeable that attendance at sessions on the last day was just as high as those on the first day, and that conversations started over breakfast continued on into the evenings. Conference attendees put in much longer hours than they do in the office.

Secondly, the organizers and presenters have realized that sessions that are little more than thinly disguised marketing pitches very quickly lose you confidence and respect. The result is that most sessions today are highly focused on presenting real world results, or best practices based on experience.

Everyone I spoke to at both conferences also believed that by being in attendance they had given themselves, and their companies, a competitive advantage. Whether it was new technologies that they hadn’t considered before, like wikis; learning how to apply industry standards like DITA; or new techniques that could save time and money, such as the application of controlled languages, or a greater use of graphics; all had come away with something that more than justified the cost of attending.

In a couple of weeks I will be at the STC National Summit in Atlanta, and I will be interested to see if the trend towards increased quality and excellence continues.

[If you are at the STC Summit I'll be speaking on Tuesday 5th May at 1:30pm in the Hanover AB room, or you will be able to find me at Booth #109 for most of the show.]

NOTE: This blog entry was first published as part of my WebWorks blog

The Future is Today

2009-04-20T15:23:00.007-05:00

Back in December I posted an entry on this blog about how observing my daughter do a homework assignment had made me rethink the way we need to approach presenting information. In business we are still bound to the book paradigm that was created in the nineteenth century, and that we, as "adults," are more comfortable with because it's the way that we were taught to find and assimilate information.

My conclusion was that today's generation approaches information gathering and learning based on a different more chaotic model, where social interaction is more important than structure. In short to survive and prosper we should start designing information not for ourselves, but for the next generation.

Today I came across this video - which makes the point much better than I ever could - the video's focus may be education, but it applies just as well to the future of corporate communications.

Writing about Wiki - New Book Project

2009-04-13T14:44:00.002-05:00

I mentioned this in passing on my Twitter account the other day, but as it was officially announced today, I thought I'd post a few more details.

WIKI: Grow Your Own for Fun and Profit
by Alan J. Porter

Looking for a way to increase team collaboration, manage your company’s knowledge? Do you need a way to manage projects with customers or suppliers outside your company firewall? Would you like your customers to provide feedback on the information you publish? Then a wiki might be just what you are looking for.

Perhaps you have already decided that you should use a wiki, but are not sure how to go about it. Maybe you have a wiki but would like to encourage more people to use it. Or you would just like to learn more about the practical applications for this fast growing technology.

Then this is the book for you.

WIKI: Grow Your Own for Fun and Profit will introduce the concept of wikis, and show why they are becoming the must-have communications and collaboration technology for businesses of any size.

The book will also include several case studies highlighting the ways that various companies are using wikis to solve differing business and communications issues, and the resulting benefits in terms of both efficiency and customer satisfaction.

WIKI: Grow Your Own for Fun and Profit will be available early next year, but we will keep you informed with excerpts and news along the way.

The official web site for the project is HERE, and it will be updated as the project progresses.

Why Technical Writers Shouldn't Be "Writers" - Slides

2009-03-26T10:38:00.003-05:00

Technical writers love the written word. Perhaps, we love it a little too much? We need to ask ourselves is the written word the best thing for documentation? Is it the best thing for us as an industry, and is it the best thing for you as a content developer.

Over the last several months I've delivered a talk entitled Why Technical Writers Shouldn't Be "Writers" at several STC regional meetings and conferences (such as last week at DocTrain West)

The presentation was inspired by an earlier post on this blog, and takes a look at why we are so focused on the written word, and presents a few ideas about better ways for us to deliver our message to the end user in a way that increases customer satisfaction.

What can we as documentation professionals learn from just observing the world around us, and how people communicate? What is the impact of new Web2.0 technology and social networks, and how they will change the way we need to view documentation design, distribution and usage?

Several people have asked for copies of the slides I used, so here they are.

However the slides are not full of text and bulleted lists, in line with the central theme of the presentation, they are mainly graphics used to illustrate an idea or to serve as talking points. This is a "performance best seen live."

If anyone is interested in me delivering this presentation to their STC group, the writing team at their company, or a conference - then just send me an email, and let's chat.

Why Technical Writers Shouldn't be "Writers"

View more presentations from 4JsGroup.

Should Customers Pay for the Manual?

2009-03-06T14:13:00.004-06:00

Yesterday a friend of mine posted the following on his Twitter feed

OMG! (Company Name) actually charges for their owner's manuals! That's absurd.

Absurd? Really? Is that the common expectation - that all the manuals associated with a product should be "free"?

Over the years I have, at different times, worked with two companies that have almost directly identical competing product lines. In general they each have around 50% of their given market (although actual market leadership tends to fluctuate between them on a year to year basis). Yet they have two diametrically opposed philosophies when it comes to supplying documentation.

Company A has the philosophy that when you buy their product you get everything included to run, maintain and operate it (but not to repair it) so they include the cost of producing the documentation in their product pricing. They make their money on spare parts.

Company B has the philosophy that when you buy their product, you just buy the product and then pay extra for the bits and services you need, as you need them, so they have a lower product price and charge for their documentation (and their spares too).

The total cost of ownership for both products over the normal operating span turns out to be just about the same.

Let's take a look at the two scenarios in more detail.

COMPANY A - Documentation Included

This is perhaps considered the more traditional model. A content development team writes the various manuals , help sets etc. and publishes a complete suite of documentation. The whole suite is then delivered with the product. That suite can range from one small manual to literally (in the case of an aircraft) hundreds of large volumes. The cost of producing those manuals is covered in the product cost, and the customer perceives them as being "free."

That's how it should be. I've been amazed at the number of times that I've done consulting work for companies that don't even consider the cost of the documentation. They don't calculate it, they don't consider it a development cost and they don't cover it in the price of their products. Often companies like that consider documentation to be "a necessary evil" (a phrase I have heard more than once) and an uncontrolled overhead. As a result the content development is not considered an integral part of the design and production process and is poorly funded (if at all). The result is usually poor quality documentation. As a general rule of thumb, if you buy a low commodity priced product and it includes "everything," then there is a fair chance that the manuals will be next to useless. (I know this is a broad stroke statement, and there are always exceptions to it).

COMPANY B - Documentation Sold Separately

In this scenario the cost of producing and distributing the product documentation is usually well understood and managed. Most products in this case will ship with a small "free" documentation set that covers the basics of getting started, and simple opertaion (like the books in you car's glove box for instance) with the expectation that if customers want to know more they are prepared to spend money. Again think of the car analogy - most people who want to maintain and repair their own cars will go and buy a book on how to do it. There are whole companies who write and sell sepcialist manuals for car dealers and repair shops. The vast majority of customers will never access a full documentation suite, so why provide it to everyone? The manufacturer can focus on producing the documentation that 80% of its customers need, and the other 20% can be covered by a recognizable revenue stream from selling the specialist manuals.

One area of opportunity where I believe that the "pay as you need it" model breaks down is that currently most manuals you pay for (including the one that my friend was complaining about) are PDFs of traditional print manuals. You still end up buying the complete book even if you only want one or two sections of it. - If you have a pay to download the manual model, why not publish it based on topics (DITA?) and use a system of micro-payments. Instead of asking customers to pay $10 (the amount that outraged my friend), $15, or $20 - why not charge $0.99 a topic?

So which one is the right approach? I think they both are. Whether or not you charge for documentation is a product of many factors such as the business plan, the content development team's role in your organization, customer expectations, etc - but one underlying thing that applies is that the cost of documentation development should be correctly calculated and factored into the product development costs. You need to recoup that costs somewhere - it just becomes a matter of deciding where in the product life cycle and how.

BUT... if I had to favor one, I'd say go the separate charge route. - it gives more flexibility for delivery, it gives the customer choice, it lowers product prices, and it turns the content development team from being an overhead into a profit center.

On a personal note, when I switched one documentation department from being an overhead to being a revenue generator it completely changed the way the role of documentation, and the people who produced it, was perceived.

And the customers liked it too.

Don't educate...learn!

2009-02-12T11:04:00.004-06:00

Earlier today I came across the following post on a Tech Doc related discussion list.

We still use X and while we (the tech writers) think they are useful, I think our users mostly rely on Y. We've attempted to educate our users on the value of X, but based on the questions I get I don't think a lot of our users think of using X on a regular basis.

(AJP - Quote edited to remove names of specific processes)

Wow - so if I get this straight, the users of the information like to use it one way (Y), but the content creators think they should be using it another way (X) so they make every effort to "educate the users" as to how it should be done.

If the majority of the people who uses your content are following the same behavior pattern, isn't it better to look at why they are doing that, and the value that THEY find, rather than the value that YOU think is there.

Learn from your customers. Find out why they prefer Y to X, and then do what you can to make Y even better. If that means dropping process X, then do so.

Those of you who have heard me talk will have heard this before, but the documentation industry is not about us as content creators, it's about our customers and how they access, assimilate, and use that content.

10 Commandments of Storytelling as applied to Tech Doc?

2009-01-13T13:23:00.004-06:00

One of the topics I am slated to deliver at various conferences in 2009 is my presentation on why I think “Technical Writers Shouldn’t Be Writers.”

Towards the end of that presentation I have a slide that mentions four recommended books as “must reads.” One of those four is Robert McKee’s “STORY: Substance, Structure, Style and the Principles of Screenwriting.”

Anyone who reads this blog will know that I’m a strong advocate of storytelling in all forms of communications. I believe that it applies as much to technical or marketing communication as it does to your favorite novel or movie.

It seems I’m not alone in that thinking. Over at the excellent slide:ology blog a recent post applies McKee’s “10 Commandments of Storytelling” to PowerPoint Presentations.

Picking up on that thought I decided to see if I could apply McKee’s 10 Commandments to Technical Documentation.

1. Thou shalt not take the crisis or climax out of the protagonists hands.
So who is the “protagonist” of your documentation? It could be your product, but the most likely candidate is that your “protagonist” is the person using your documentation. Your documentation should be written in such a way that your protagonist can use the information so that they feel that they have solved the crisis (or put more prosaically, overcome the problem they have) themselves based on the knowledge you have presented. Another story telling trick, often cited by screen-writer Todd Alcot, that is worth remembering – ask yourself “What does the protagonist want?”

2. Thou shalt not make life easy for the protagonist.
This seems contrary to the very purpose of Technical Documentation. Isn’t it our job to make life easier? Yes it is. But in certain types of documentation, such as training materials, you may want to include challenges, and then guide the reader through them. This way you can build a sense of accomplishment as the reader progresses through the material.

3. Thou shalt not use false mystery or surprise.
Don’t hold back anything that is integral to full understanding of the product or service you are writing about. But also make sure to reveal information in a logical manner that is considerate of the reader’s needs. Make sure they have the information they need to know, at the time they need it.

4. Thou shalt respect thine audience.
The first rule of any sort of writing is “know your audience.” Know them, and respect their level of knowledge. If you are writing something for experts, then you may not need to include the basic information that you might use for a more general consumer market. The use of conditional text is a great way to handle different topics and statements designed for different audiences within a common documentation set.

5. Thou shalt have a god-like knowledge of your universe.
A joke I often use is “What’s the definition of an ‘expert’?” – The answer is “it’s a person who has read two more pages in the manual than you have.” So what does that make the person who wrote the manual in the first place? We may not know everything about what we are documenting, but we should give the reader the confidence that we do.

6. Thou shall use complexity rather than complication.
Most of what we write about in Tech Doc, is by its very nature, complex. We should take that complexity and break it down into logical steps and topics that can guide the reader. We should never use complexity as an excuse for making the documentation complicated.

7. Thou shalt take your character to the end of the line.
We learn in grade school that every story should have a beginning, a middle, and an end. The same applies to documentation too. The narrative should guide the reader through the process, or information, in such a way that it flows logically, and that at the end they know more, or have achieved more, than when they started.

8. Thou shalt not write on the nose dialog.
Wait, I hear you asking, there’s no dialog in Tech Doc – so how does this apply? Well the definition of “on the nose dialog” relates to the scene when a character says aloud, exactly what he is thinking or describes what is happening around him. So how does this apply to Tech Doc? Do you have sections of doc that are restating the obvious? Try reading your docs out aloud? Is it boring and repetitious? Try altering sentence lengths. Don’t think anyone ever listens to docs as if it was dialog? As a teenager I spent hours working under cars while a buddy nearby would read the steps from the manual for me to follow. How about a visually impaired customer using a reading device?

9. Thou shalt dramatize thine exposition.
Put simply “show don’t tell.” In prose this means have your characters reacting to an event, not talking about it. But isn’t our job to tell people how to do something? Yes it is, but the key word is “how.” Replace long descriptive texts on operational theory with a few active steps the user can take themselves, that demonstrates the product, and they will gain a quicker understanding. People learn more by doing than they do by being told.

10. Thou shalt rewrite.
Do I need to explain this one? Plan your schedule with time to write, have someone else review, and rewrite. Best of all scenarios is to write, have someone actually use your draft to accomplish the tasks you have written about, get feedback. Better yet, watch them try to use your docs. Then go back and rewrite based on your observations. They say that any good piece of art is never finished. Writing is art, even Tech Writing. You can always improve on what you’ve done.

Banging The Drum Again...

2008-12-12T09:30:00.003-06:00

In his excellent blog post about the current state of the book publishing industry Mark Tavani, a Senior Editor at Random House, makes the following observation.

... books are a mere format. Yes, they can be beautiful and wonderful to hold in your hands, and yes, there are some books I plan to keep in my home until the day I die simply for their sentimental value. So I understand what is magical about books. But the most magical thing about them is the information they convey: the story they contain. The word “book” and the word “story” are not synonymous, just as eight tracks and music are not the same thing. Stories pre-date books by milleniums; and though books might someday go away, story will last as long as our civilization does.

Substitute the word "book" for "documentation," and the word "story" for "content" and I think the observation applies equally to the world of corporate publishing as it does to traditional book publishing.

=========

I need to add a couple of points of clarification here.
- Anyone who knows me and has heard me speak will know I love books (the traditional kind). I have a house full of them, and spend my evenings and weekends writing them. BUT while I'm a passionate bibliophile, I am also aware (as I mentioned in my last post) that the "book model" is perhaps no longer the best model to be using to ensure that content reaches the end user of a product or service.
- While I suggested swapping the word "story" for "content" in the quote above, that was more to illustrate a point. For me everything we write or produce that is designed to pass on knowledge or information is, and should be treated as, a story. The ability to tell stories is the most powerful communications tool we have at our disposal. As Tavani points out, we've being doing it for millennium, and will continue to do it irrespective of any technology or medium.

Move over DITA – Chaos is coming!

2008-12-08T17:01:00.004-06:00

I’ve never really questioned the need for hierarchical structure and imposed taxonomies, - until I watched my teenage daughter doing her homework several months ago.

Let me explain.

I’ve been working with topic based authoring, structured content and mark-up languages for over twenty years now. This highly formalized approach to technical documentation has always seemed to be the right approach to take in handling larges amounts of complex information, and delivering it in a way that enables relatively easy navigation.

I’ve seen them all come and go – SGML, DocBook, XML, CALS, DITA plus a ton of various industry and company standards. I’ve even served on several such standards committees and working groups in my time.

For those of us raised on more traditional media (i.e. the printed word) we are most comfortable with the book paradigm. That information should come in a structured format, i.e. Chapters with Headings and Sub-Headings, and that navigation is best accomplished by either a map to that structure (i.e. a Table of Contents), or an alphabetical listing of subjects covered (an Index).

Naturally when we started to deliver information electronically we carried that paradigm over. Sure we made a few concessions to the new media (for instance I remember having a long, and somewhat heated discussion on why we didn’t need page numbers on a CD deliverable); but the underlying print based model stayed. Because that’s what we were comfortable with. It’s what we naturally understood and it matched the way that we handled locating and using written information outside of the work environment.

In fact for most of my working life to date, the technology I used at work far out paced that I used outside of work.

But not any more.

Now the technology I use at home has generally outpaced that found in most workplaces. In particular social media and the way that we look for information online.

Helping my teenage daughter with a school project on Pearl Harbor made me realize that the new generation now entering the workforce has a completely different way of accessing information.

Of course the first thing she did was google “Pearl Harbor” and started visiting links. First stop was Wikipedia.

Then she got on Facebook and YahooIM and started using messaging to ask friends who were online for recommendations. These friends were literally from all around the world, so she was given access to resources that gave totally different perspectives than those given in the classroom. As I watched she soon had six different windows open on her iMac and was pulling information from multiple sources into her own document. Building the structure and narrative as she went.

One friend suggested going to a social bookmarking site and searching using a variety of user applied tags. Instead of taxonomy she was now applying folksonomy.

Of course being a bibliophile and a bit of a history geek I had a few good old-fashioned print books on World War II sitting in my home office. I proudly placed them on the edge of my daughter’s desk and suggested she look through those for information on Pearl Harbor too.

She dutifully picked up a couple of the books and started flicking pages over, skimming through the contents.

“Why don’t you use the Table of Contents of Index?” I asked.

“That just confuses me. I can find stuff quicker this way,” she replied, looking in bemusement at her obviously aged father.

I sat back and watched her navigate the books for a few minutes. She quickly found what she needed – and then I realized what she was doing. She was “browsing” just as if she was online.

That’s when I started to question the paradigm that’s informed the way I’ve thought about online documentation for over two decades. The book driven, structured paradigm may have been ideal for my generation, but what about the new generation?

For kids raised as part of the “digital generation” where the first place they go to find out information is the internet and social networks, is the book an irrelevant model?

Yes the information they access still needs some sort of mark-up and tagging so the search engines can find it. It still needs metadata to enable user tagging. But instead of strictly enforced hierarchies, what is being built and accessed is more of a flat ocean of information (or a “Content Pool”) that users search rather than navigate, and then dip into to find the components they need to build their own solutions.

So where does that leave current favored structured standards like DITA? I believe they have a place in more rigidly defined and regulated environments, but how long they will remain useful is open to question.

As for more general applications I believe we need to stop trying to shoe-horn the current “flavor-du-jour” standard onto every publishing project, and instead take a step back and look at how your kids do their homework. Because in five to ten years they will be your new workforce, and perhaps more importantly, your new customers.

Remember the (STC) Alamo

2008-11-25T14:56:00.003-06:00

Just over a week ago I attended what was simply the most open and stimulating regional STC event I have ever been to.

The Central Texas STC Fall Seminar, was organized jointly between the Austin and San Antonio chapters of the industry group and held at the excellent Hotel Valencia on San Antonio’s famed Riverwalk. (Home to many fine restaurants - including the one where we had lunch.)

But it wasn’t the setting that made it memorable – it was the participation.

In my experience a lot of these regional get-togethers end up in features and functions comparisons of tools, minutiae of the job, or arcane technical discussions about standards that only a minority of people use. Not so in this case.

The discussions ranged from using emerging new technologies, Web2.0 tools,, wikis, social networks, to how to develop and recognize metrics, to how to make sure that the documentation process is heard and accounted for in a Agile Development driven world.

But underscoring all the talk of technology was the realization that technologies will come and go, and the most important skill to develop was the ability to learn about new things, and communicate that in an empathic way.

There were several people who were attending their first STC event and they, along with everyone else, left with the impression that this is an exciting time to be in the corporate publishing world.

Is there a case for "Just Enough" Documentation?

2008-11-20T15:59:00.003-06:00

A couple of what at first glance appear to be disparate unconnected posts picked up by my Twitter feed over the last few days got me thinking about just what we should include when we produce product documentation.

On her Twitter feed consultant Sarah O’Keefe posted the following quick observation: "Inbox Zero once again. Today's lesson: When you ignore stuff, much of it becomes irrelevant.” This is a productivity, time management technique that I have used for years. One of the first things I was taught at management college was that never keep anything on the “to-do” list longer than 30 days. If you haven’t got around to it in 30 days and no-one’s complained it probably wasn’t that important. Delete it, and if it is important someone will remind you. Like Sarah I also apply a similar philosophy (but not time scale) to the contents of my Inbox.

Then today, Alyssa Fox from NetIQ posted a quick note on her Twitter feed that “SE just found a bug in our doc that's been in there 5+ years. Obviously no one ever reads that section,” to which I responded “If no-one's read that doc in 5 years - is it really necessary to have it there at all? Why write and maintain something no-one uses?”

Over lunch I began to realize that the two thoughts had a definite connection. Traditionally we tend to document every feature and function of a product. We expend many hours describing how something works. Yet how much of what we produce is ever read or used?

Most users are only interested in learning how to set something up and start using it in the shortest possible time. Secondly they want to get answers to very basic “how do I” type questions. With this in mind I’ve recently been conducting an ad-hoc, and very unscientific, straw poll about which documents (print, on-line help etc.) that people are most likely to use. The result is very clear that the thicker and more voluminous the documentation appears, the less likely people are to use it.

So going back to the “ignore it and it becomes irrelevant” thought. If sections of documentation are never read, accessed or used, are they irrelevant? While the engineers and designers may not think so, it seems clear that the users do.

Is there a case for “Just Enough” documentation.

At WebWorks.com we recently went through a process of rewriting our complete documentation set. At least that was the original goal. Yet when we compared the old documentation set against the project time frame we realized that we would have to make a decision about what was necessary and what was just “nice to have.” The project was lead by one of our MVP users who could give us the user perspective on what was needed and what could be left out.

But how will we know if we’ve made the right choices?

We posted the new documentation set online as a wiki. We have enabled comments so users can directly tell us if there’s something we missed. If we need to, we can create a new piece of documentation and publish it quickly. But perhaps best of all we can now track which document pages are visited and more importantly which aren’t.

It may take a few iterations but we will be able to fine tune the documentation to provide just the information that our users need and use; allowing us to focus effort away from maintaining “irrelevant” dead pages to making sure that he have “just enough” documentation to make our users successful.

[This entry is cross-posted to my WebWorks.com blog]

STC Proposals #3 - What Tech Doc Can Learn From The Comics

2008-10-09T13:40:00.001-05:00

Proposal for a paper to be presented at the 2009 STC Summit in Atlanta, GA

#3 - What Tech Doc Can Learn From The Comics

The recent Google Chrome comic caused a lot of buzz. But it's far from being the first "technical" comic. Find out how comics can help you produce better tech docs.

There is a long tradition of connections between the worlds of comic books and technical documentation, but it is one that is often overlooked. (For example the US army has used technical comics for over 50 years)

This presentation will present examples of technical documentation done using comic book techniques from over the years to the present day.

It will also show how by studying the story telling and artistic techniques used in comics we can improve the readability and quality of technical documentation.

STC Proposals #2 - How To Make Executives Love The Publications Department

2008-10-09T13:36:00.003-05:00

Proposal for a paper at the 2009 STC Summit in Atlanta, GA.

#2 - How To Make Executives Love The Publications Department

"The publications department gets no respect" is an often heard refrain. But it need not be that way.

It is possible to make Publications one of the most respected groups in your company?

Building on my own experience of doing just that, this presentation will show five key steps to take in order to change the way people think about publications.

The lessons presented can be applied equally to a single writer, as well as to larger publications groups.

STC Proposals #1 - Move Over DITA, Chaos is Coming

2008-10-09T13:29:00.004-05:00

Last week I submitted proposals for three papers for the 2009 STC Summit in Atlanta GA, and thought it might be fun to post the summaries here. Let me know if you'd be interested in hearing any of these and if so, what sort of questions you'd like answered or topics you would like me to cover.

#1 - Move Over DITA, Chaos is Coming

The Technical Publishing industry is on the edge of a paradigm shift and may not realize it.

As the digital generation enters the workforce they will bring new expectations with them that will challenge the way we write and deliver content.

This presentation will contrast the way we currently produce documentation and our expectations of user behavior with what we can expect our users to be asking for in the not too distant future.

In the world of social networks, online video, wikis, blogs and twitter is structured topic based authoring really the answer?

Reflection on Santa Fe

2008-10-03T14:05:00.002-05:00

I must admit after last year's excellent CIDM Best Practices conference, this year's event in Santa Fe was a little disappointing.

I didn't really hear anything new from the presentations, while the networking and side conversations seemed somewhat subdued. I had a couple of good productive pre-arranged one-on-one meetings, but otherwise there was no real discernible "buzz" about this year's event.

Difficult to say why, as that's more of a subjective feeling than an objective observation.

One thing that did surprise me was the fact of how many people still overlook both the importance of graphics, and the impact of the whole publishing process once the content has been created.

Creating good technical documentation is not just about authoring and content management.

NM bound

2008-09-12T10:37:00.002-05:00

This weekend I'll be on the road heading to Santa Fe, NM to attend the upcoming CIDM Best Practices conference.

I'm looking forward to the conference, meeting up with some old friends, and hopefully learning a few new ideas and concepts about the art of Corporate Publishing.

Instructional Comics - Google Weren't The First

2008-09-11T14:18:00.006-05:00

As part of the on-going online discussion about the impact and usability of the Google Chrome comic, fellow blogger Tom Johnson asked me if I had more samples and references for comic book style documentation.

As I mentioned before the "technical comics" I've done to date have been more like illustrated white papers than "how to" instruction manuals, but over the years I have come across a few examples of instructional comics.

Perhaps the best known among the comics creative community is the work done by pioneering graphic novelist Will Eisner for the US Army. Between 1951 and 1972 Eisner produced the P.S. Magazine - The Preventative Maintenance Monthly for the army, which combined comics, instructions and some great artwork covering a whole range of army equipment and procedures.

(The Virginia Commonwealth University has a complete digital library of PSM available online.) He also wrote and illustrated an document known to the US army as "DA-Pam 750-30 - The M16A1 Rifle - Operation and Preventive Maintenance" - but generally referred to as "Treat Your Rifle Like A Lady."

Other examples I've come across include:
- Emergency Roofing
- Playing the accordion.

And there are things like aircraft safety instruction cards (the ones in the seat backs) and numerous instructional notices (like this one about using your cell phone on the subway) that use comics iconography and techniques.

Wanna Be A Tech Writer..

2008-09-09T13:58:00.001-05:00

As someone who has more than a passing interest in both The Beatles and the world of Technical Writing - I just had to share this...

The Google Chrome comic - why it didn't work.

2008-09-04T14:06:00.003-05:00

Yesterday I spent a fair amount of time talking with a prospective client about a project involving the use of sequential art to convey some very technical information.

In short, he wants to use the medium of comics to tell prospective engineers why it would be cool to work on the projects his organization is responsible for. (And having heard what projects they are – I can confirm it would be VERY COOL to be involved in almost any capacity).

I walked him through the process I use to develop and produce promotional comics and various options for delivery etc. based on budgets, audience and so on.

During the conversation the “technical comic” produced by comics guru Scott McCloud in support of the launch of the new Google Chrome browser was discussed.

My client had loved the idea, checked out the links, started out to read the McCloud comic and after about six pages he had glazed over, skim read a few more pages and not actually finished it.

His concern was that he was not alone in this reaction, and because of this was wary of citing the Google comic to his budget holders as a way to justify his own project.

Even with the added incentive of professional interest, I must also admit that I found the Google Chrome comic difficult to finish. No one else I have spoken to since has actually read it the whole way through.

Why? Because despite the “novelty” of the method of presentation, they didn’t stay engaged in the subject matter.

Today I came across the following quote from Scott McCloud in an FAQ.

Who wrote the script?
The engineers, for the most part! I helped conduct interviews with about 20 engineers who worked on the project, then adapted what they said into comics form. Some paraphrasing, lots of condensation, and one or two late drop ins, but basically it was a very organic adaptation and I had a lot of latitude.

And perhaps there lies the problem.

There is no single voice and no narrative.

Let me say that I greatly admire McCloud. He knows more about comics storytelling and structure than I ever will. I constantly reference his classic work “Understanding Comics” in producing my own work, and in various papers I write, or presentations I give, on communicating.

But I’m amazed with the Google project, because the lack of narrative seems like a basic omission from such a high profile project.

Whenever I produce a promotional comic I always try and include a central character that the reader can empathize with, along with a story (more often than not something light and fun to off set the heavy technical jargon) to guide the reader through the points being made.

As I’ve often said before, all communication is a story and technical communication needs it just as much as fiction.

I’m not sure what audience the Google Chrome comic was aimed at. While it was great to see comics used in such a high profile way, did anyone consider the implications and impact of the fact that the very use of the comics medium would expose it to a wider audience than first intended?

I bet you don't think you're this bad...

2008-08-07T08:24:00.003-05:00

I'm not sure if this is genuine or something put together as an example of extreme technical jargon - whichever it still provides one of the best demonstrations of the need for clear concise communications in presenting technical concepts.

You may not think that your company or industry jargon is this bad, but try a little exercise. Take a white paper, or sample page of documentation and show it someone (family or friend) who has no experience of your industry and ask them to read it. See how many words and phrases they stumble over.

How far do you spread the message?

2008-07-14T13:39:00.003-05:00

Yesterday afternoon I spent some time posting sample art from an upcoming comics project on my personal blog as well as in a publicly accessible Facebook photo-album, and making sure I mentioned it on Twitter.

Part way through the exercise my wife asked me "Why are you doing that. Shouldn't the publishers be doing it?" On the face of it it seemed like a fair question, but experience has quickly taught me that publishers with hundreds of books to promote can only focus on a select few, and you can't count on yours being one of them. The more marketing you do for yourself the more advance interest you can build and, hopefully, the greater the sales.

Switch to this morning at the WebWorks office, and after reviewing some figures I sent an email to one online distributor of software asking them to remove our product listing from their website.

The two events didn't seem related, but over lunch today I began to think about it.

Last night my underlying philosophy was that "the more marketing the better." The more online exposure I could get for my upcoming project the more awareness it would build for both the project and myself as a writer. So more is good? - Yes

This morning, when I looked at the product listing online at the site in question I saw that the product and company descriptions were years out of date. They obviously had no real understanding of our market, or what business issues our product helped solve, never mind its actual features and functionality. When I looked back at the records I found that they were one of a large group of on-line software distributors who had been signed up "en-mass" several years ago. The philosophy had been the same as mine the previous night "the more web presence the better." So more is good? - In this case - No.

So many distributors had been signed up that no-one was (or could practically for our size of company) manage them all and keep track of how we, and our products, were being represented. The ones that produced steady strong results got noticed and managed. The ones that only produced occasional sales didn't. The result is that those neglected listings were soon sending the wrong messages.

So what's the connection? Having a philosophy of spreading your message far and wide over the Web can be a great one. In today's Web2.0 world viral marketing is one of the strongest marketing tools available. BUT.. you can should only spread the message to places that you can manage. If the message gets inconsistent and diluted it doesn't take long to become worthless.

Story Quotes

2008-06-26T16:36:00.002-05:00

A couple of great quotes about the power of stories in business that I came across today.

"Good leaders are good authors of stories that include everyone else."
- Gerhard Gschwandtner - SellingPower.com

"Stories give us context, and context helps everyone understand."
"Stories wield special power because they can be translated into something visual. When we hear a story we see it too, and the visual image becomes something that sticks in our memories long after the words have fled."
- Harry Beckwith & Christine Clifford - You Inc.: The Art Of Selling Yourself.

Now Twittering..

2008-06-25T22:31:00.001-05:00

Just a quick note to let you know that if you feel so inclined you can know follow my random thoughts on a variety of subjects via TWITTER at http://twitter.com/gothamajp

Emotional Warning Light

2008-06-25T15:52:00.006-05:00

I’ve long been an advocate of the advantages of using a controlled authoring vocabulary in producing technical documentation. The concept of one word = one meaning is central to this concept and is the underpinning of standards such as Simplified Technical English (STE).

In short ambiguity can lead to mistakes, or in extreme cases even cause fatalities. But one thing I hadn’t thought about before is that as well as considering the literal meanings of the words and phrases used, we should also consider the emotional and psychological impact.

It was an article by veteran racer and motoring journalist Denise McCluggage in a recent (16 June 2008) AutoWeek magazine that opened my eyes on this subject.

Denise’s article discussed the impact of the “CHECK ENGINE” warning light common in most vehicles today.

By all the rules and principles of controlled authoring that’s a perfect valid warning statement. Clear, concise, using simple words with well defined meanings.

But as Denise points out it has the potential for two distinctly different emotional impacts.

For a typical car guy (like me) the response to the “CHECK ENGINE” warning may be “rats I need to take the car in to the dealers at some point, where they will do some minor adjustment and charge me an arm and a leg for it.” After a few go-arounds when the car doesn’t do anything untoward they may even ignore the warning altogether.

But for a female driver the response to the “CHECK ENGINE” light may be concern that the engine, the thing that makes the car go, is about to fail and leave her stranded at the side of the road. Her reaction maybe that that warning could lead to something that will put her in a potential life-threatening situation.

As Denise goes on to point out the “CHECK ENGINE” light really means that “something might be amiss with the emission system and you should really have it looked at next time you are in the shop for routine maintenance.”

So the choice of words is not as good as I first thought it was. Maybe it should read “Emission Controls Service Due.”

In short this article made me realize that as well as making sure we use the right vocabulary we should also be taking just as much notice of technical context and audience psychology.

Preparing technical communication is not just about passing on knowledge, its also about the emotion with which the message is received.

Business and Storytelling

2008-06-12T15:57:00.003-05:00

Anyone whose spoken to me for more than a few minutes will quickly find out that my passion is story telling. In fact I believe that ALL business communication, be it in sales, marketing, technical publications, white papers, reports, even simple emails, is simply different forms of telling stories.

Sitting on my desk next to me is a book with the great title Whoever Tells The Best Story Wins. I'll be honest I wasn't too impressed by the actual content - but I keep it on my desk so that every day I see that title.

Today doing some business plan research I was looking for examples of the ultimate in business story telling - The Elevator Speech.

What's an Elevator Speech - the idea is that if you are riding in an elevator and someone asks "What does your company do?" - you can answer before the elevator ride is over. In other words you can tell your business story in less than thirty seconds.

That research lead me to the video below.

The video has some good pointers on composing a good Elevator Speech - but what really caught my attention was the idea of a CEO using the job title "Chief Storyteller." - That's a job title I think we should all adopt, at least in spirit if not in practice.

Why Technical Publishing Shouldn't Be Art..

2008-06-10T14:56:00.002-05:00

“Writing is a solitary occupation. Publication is a group exercise,” so stated novelist Madeline Robbins in her February 25, 2008 blog entry on the DeepGenre web site. And she’s correct. The work may start with the author, but to get it from the author to the end reader means it also has to go through an editor, copy editor, book designer, typesetter, printer, sales and marketing team, distributor, book buyer, and, eventually, a retail store.

It’s a model that the book market developed centuries ago and still works today. Although it could be argued that the Web and print-on-demand are altering the delivery mechanisms slightly, the same basic process still applies. The book trade is based on the fact that the artistic elements, the creation of the content, and the design of the book are small parts of the overall process, and that the publishing process is a business that only flourishes through being scalable and repeatable.

Yet the more I write books and the more I become involved in the book business the more I am struck by the differences between it and what has been my “day job” for over twenty years, technical publications.

Over the years, I’ve been trained and worked as a writer, editor, document designer, coder, formatting expert, content management specialist, and workflow designer. I’ve used software tools that applied to every one of those disciplines. And here’s the point: often at the same time.

Click here to read my full article on "Why Technical Publishing Shouldn't Be Art" at Techcom Manager

SaaS Publishing

2008-02-10T17:32:00.000-06:00

A couple of weeks ago I attended a software industry business conference in Atlanta. The hottest topic under discussion was the shift from traditionally licensed, on the desktop, software to Software as a Service, or SaaS.

The SaaS model replaces desktop processing with the work being done by remote servers located “out there” in data centers and accessed via the internet. For those of us who’ve been around the IT industry long enough this is nothing new. It’s reminiscent of the old mainframe / dumb terminal model. The biggest difference is that now the processing power is the responsibility of the software vendor and instead of a dedicated network access is now, theoretically, from anywhere at anytime.

The poster child for SaaS is Salesforce.com, and the seems ideally suited to enterprise wide business systems. But isn’t publishing also an enterprise wide activity (even of 90% of enterprises don’t recognize it as such). Is there a role for a SaaS solution on publishing?

In some ways we already have them, blogs (like this one) and wikis are SaaS models where all the processing, storage and delivery is done via a web server with no specialist editing software on the host machine.

With both blogs and wikis gaining wider adoption in the Corporate Publishing world, will more traditional editing, content management and publishing tools be far behind?

STE at the STC

2008-02-10T17:13:00.000-06:00

The presentation on Simplfied Technical English at the Austin area STC meeting last week appeared to be well recieved. As well as generating discussion, both at the meeting itself, and at the dinner afterwards, I also received several follow up calls and emails over the days following.

Mary Conner if iMIS, who was in the audience, blogged about the event, and for those interested you can check out my presentation slides below.

| View | Upload your own

Four Candles - Just What is Simplified Technical English?

2008-01-23T09:24:00.001-06:00

On the evening of February 5th I'll be presenting the following at the Austin area STC meeting:

Four Candles - Just What is Simplified Technical English?

You may have heard of Simplified Technical English as a way of writing your Technical Publications in order to reduce translation costs, but it applying the concepts of STE can bring benefits to all your technical writing whether they are translated or not. This presentation will cover the story behind the development of STE, plus introduce its basic concepts and explain how you can start applying them and improve the quality of your technical documentation immediately.

So why is this talk titled "Four Candles" ? This may give you a clue..

So that's why my bookcases are so full...

2007-11-02T16:17:00.001-05:00

I earn my daily crust in the world of digital publishing. Given the opportunity I will happily talk about all the advantages and cool stuff you can do with digital content. (like post this to multiple blogs using a single editing tool.) In fact I tend to think that today we are living in the "promised world" that I've been looking forward to in my twenty plus years of being in Corporate Publishing - the technology has at last caught up to the potential. But that's possibly a subject for a whole other post.

Yet when I wear my other hat as a freelance writer it's mainly for print publications. Give me a spare half-hour and you will likely find me hanging out in a traditional bookstore. In fact just last night I was sat in the coffee shop area of my local Barnes & Noble, working away with pen and note pad on a pitch for a graphic novel, while just a few feet away on a nearby shelf sat several copies of the book containing my recent James Bond feature.

I just can't get enough of print. I still read literally hundreds of print magazines a year and average over a book a week. But why, when I spend a large proportion of my life expounding the virtues of digital publishing does ink on paper have such a hold?

Today a print copy of the latest Seybold Report landed on my desk and my eyes immediately drifted to an article entitled "Is Print Sexy?" by Laruel Brunner. In the article Brunner eloquently managed to sum up the appeal of print. Here's a few choice extracts that I think best sum up my own views.

We trust print's permanence and we rely on print to document our world truthfully and to accurately enshrine our most precious values and ideas of the world around us. We believe, rightly or not, that it provides our foundation for fact. It's how we preserve and revere our collective experience and perceptions .......print is uniquely physical. Like all media it expresses concepts, ideas and information, but it stimulates response using more subtle, tactile techniques. We have a singularly intimate and physical relationship with print, because it appeals to virtually all of our senses. The look of a magazine, the smell of a new book.. all stimulate us visually and sensually. We love the look, smell and feel of print and of course its practicality. Print is portable and robust, it's accessible and easy to use...A shelf full of books is a collection of old friends who will never disappoint us and who remind us of who we were and of worlds long gone, showing us how we have become who we are....All of life is about stimulation and response, and print is all about life.

I couldn't have said it better myself.

ScribeFire Test

2007-10-04T09:24:00.001-05:00

Test posting to multiple blogs using ScribeFire