Posted by: Ben Mansheim | July 23, 2009

Another look at Miriam’s original point

Tom Johnson’s article What Users Don’t Care About follows exactly on the point that Miriam made many moons ago. The article is great and the comments made by some of the big movers and shakers in our profession are even better.

Posted by: Yisrael Woolf | May 20, 2009

Free documentation: Problems and Potential

Why pay if you can get it free?

One of the main challenges our profession faces is the proliferation of good documentation that’s free. Management increasingly will ask why they should pay us if the same product is available at no cost.

And let’s admit it – sometimes (dare I say “often”?) the free documentation is better than what we charge to produce.

A cautionary tale

There are many examples of free documentation. Let me tell you just one recent story.

I wanted to quickly learn the basics of a particular DTP tool.

I downloaded a free 30-day trial version along with the documentation, launched the application, and dutifully clicked the Tutorial link.

The link blinked. I had the uncomfortable sensation that it was winking, taunting me. Nothing else happened.

A computer re-boot later, it was the same story.

Okay, I thought, I’ll fall back on our profession’s favorite nasty motto: RTFM.

Well, presumably the manual covered the basics, but I’ll never really know. Because it covered so much, in such excruciating detail, with endless cross-reference links, and with poor search capabilities.

There were other “out-of-the-box” types of documentation, some of which required downloading specific applications. None was of any use.

The obvious solution

Increasingly frustrated and with a looming deadline, I called my favorite computer troubleshooter – Leora Livneh. She suggested today’s obvious solution: “Google” the product name along with the word tutorial.

She specified one caveat: Don’t look at anything that’s provided by the company that produces the product, since it typically isn’t worth much. “Don’t take this as an insult to your profession,” she said. Naturally, I immediately took offense.

As if she had waved a red flag, the very first thing I did after receiving a wealth of promising tutorial links was to click on the one with the company’s URL.

There were tons of tutorials. None explained the product version that I needed. Red-faced, I resolved never to tell Leora about not having heeded her one warning.

Getting back to the search results, my preference was for a video tutorial. After tweaking the criteria, the search engine displayed a digestible list of hits.

While checking out the most promising links, two annoying obstacles took turns flashing on the screen: Download a specific player (again!), or everyone’s favorite error message – file not found.


So I went back to the search and selected a text-based tutorial series – one not provided by the tool’s producer.

Over the next couple of days, I did the introductory tutorial procedures, read the concise overviews provided at the beginning of each section, and dipped in and out of areas that were of particular interest.

After investing several hours, I got a handle on the basic concepts, tried out the most important features, and glimpsed the more advanced capabilities.

I would have gladly paid the company to get the effective introduction that I found for free.

Morals of the story

What lessons can we learn?

First, in trying to provide documentation for everyone, we sometimes serve no one.

We need to build into documentation systems the capability to tailor the content for the user. A few simple questions about the user’s level (beginner, intermediate, advanced, upgrader) should result in focused information.

The technology is available now. We should use it widely.

However, just using fancy new delivery systems does not guarantee any better results. The tutorial I used consisted of simple HTML text files with a few links and a couple of illustrations. But it was what a beginner needed, and the language and content consistently reflected that.

On the other hand, the newfangled systems provided with the product, which required downloading new applications, had neither intuitive user interfaces nor sufficient search capabilities.

A standard browser search engine yielded reasonable results in a few clicks. The documentation we provide, which is much smaller and more focused, should be easier – not more difficult – to search.

Video: Promise and pitfalls

While video is an attractive and in-demand training method, it can be tricky.

The costs and time involved are usually significantly higher than for other solutions.

The costs increase even further when we produce sufficient variations to satisfy the needs of the different levels of our audience – as we should.

It is also challenging to ensure that the video is compatible with a variety of players. Few things annoy users more than clicking on a video link and getting an eternally rotating circle or an overly enthusiastic message to “Just take 30 seconds to download SuperDuperPlayer and your video will start automatically! We Promise!! REALLY!!!”

Raising the bar to provide video content is not a free pass to let other stuff slide, like maintenance, usability, and accessibility. It just may make those things more costly and challenging to provide. A careful selection of video and graphic tools should take these crucial issues into consideration.  

Making the business case: Free and easy

There’s no turning the clock back to when our users were a captive audience. I doubt that they were happier then, either. They were just more frustrated since if they couldn’t find the answers quickly in our documentation, they felt totally stuck.

On the contrary, we need to argue that happier customers are more likely to stick with our product, use the upgrades, and purchase other products that our company produces. Informed users are a business asset.

So we should convince management that it makes sense to pay us and then make our documentation products free and as easy to access as the other information that our customers find useful.

Our challenge is to provide information that is even better than the material that’s currently generated for free. When we demonstrate that this helps keep our customers loyal, management will be more than happy to pay us.


There are many types of free information, such as user groups. Please share your thoughts on their specific problems and potential.

Posted by: Ben Mansheim | May 17, 2009

Will the Wiki Waste aWay?

I owe the blog a post about the STC 2009 Summit in Atlanta (which was really great), but to buy myself a little time…

I StumbledUpon this post from Matthew (not Arthur) C. Clarke about the current use of wikis in the enterprise. Among the comments about innovation have been mentionings of wikis as an example of the cutting, or bleeding, edge. I think Matthew does a great job of defining the ways that wikis will continue to enhance the way enterprises communicate internally and externally, and why they will eventually go the way of the cassette player.


Posted by: Yisrael Woolf | April 28, 2009

An Innovation Specification

People have asked: How do you go about innovating in technical communication?


Should we willy-nilly adopt every fad? We all know that most fads fizzle out.


Ah, but then there are the revolutionary ideas that really take off and completely change the way we work, play, and think.


For example, almost every verb and noun in these sentences would have been meaningless a few years ago: I’m blogging on a laptop. I link to the blog, which has an RSS feed, on my social media site.


It is hard to tell what the next successful invention will be and how technical communicators should respond to it.


You may also ask: What about the progress we have made? For instance, should we throw out all the CMSs, XML, and structured chunks that we worked hard to produce? Clearly not.


But we are missing a set of requirements for how to innovate.


We need to refer to a spec that would provide innovation development guidelines, nudge us in the right direction, and build on the existing tech comms techniques that are most adaptable and promising.


It would also provide managers with a tool to assess the methods we advocate.


I don’t know of such a document. So let’s create the Great Technical Communications Innovation Specification. (Alternative titles will be gladly accepted!)


As with all good documentation, let’s start with a scope and an outline.


The spec’s scope would be to answer the following question: 

What is required to effectively convey information that users need about technology that exists or is being developed?


True, implementing the spec won’t give us a crystal ball to see into the future. But if we can come up with solid requirements for the stuff that’s out there and that’s currently under development, we’ll have a much better chance of handling the next generation of technology.


Here is an initial stab at some high-level requirement areas that the outline should include:

  • Mobility
  • Accessibility across platforms
  • Usability
  • Modes (audio, visual, tactile)
  • Audience analysis
  • Constraints  (such as time, display size, file format)
  • Code documentation (Architecture, API, Design, Requirements, Test)
  • User interface documentation
  • Reuse
  • Integrating documentation with source code
  • Support of development environments, including Scrum/agile
  • Social media

 This list was stream of consciousness. I need your help to:

  • Comment on the proposed items.
  • Prioritize the requirements.
  • Fill in missing high-level requirements.
  • Suggest ways to proceed.

Specifically, we’ll need to sort out:

  • What’s the best way to maintain and develop the spec? (A Wiki?)
  • Should we start by fleshing out only the highest priority requirements?
  • Any ideas for a killer review process?

 Thanks for your cooperation. Let’s start specing!

Posted by: Kelli Brown | April 16, 2009

Getting back to that challenge…

Several weeks ago, I challenged other would-be innovators to try something new. Take an existing PowerPoint presentation and mix it up with a podcast (for those of you who are already intimidated, a podcast is only an mp3 file). I asked folks to send in their links so that we could share.

Unfortunately, I’m still waiting to receive my first link. 😦

Meanwhile, I went ahead and did one myself. It’s not perfect, but it’s getting a lot of views and has already helped me to meet new people in my niche. I’d go so far as to call it a success. And I learned a lot (!) doing it.

Feedback is welcome, but please be gentle – it’s my first try too.

Here are my tips – things I learned from this first effort:

  • If you don’t have some awesome software (Adobe CS4 comes to mind), you still have what you need. I used my Skype headset with microphone and Audacity (free). You can find out more about recording a podcast here.
  • I recorded in my office (which is our safe room) without anything to dampen background noises, etc. The sound quality isn’t perfect, but it’s usable.
  • I did the whole thing in two halves and married them together with Audacity. You can do a lot with that program – I took out a bit of my umming and hmming and uhhing, but could have made the whole thing a lot smoother with a little more time.
  • I didn’t rehearse ahead of time, but it’s good to review your slides so that you can move quickly between slides.
  • Remember to speak slowly – I forgot.
  • This is really fun. I had a great time doing it and look forward to doing more of them.

After you record the audio, you put it online where SlideShare can access it (yes, you can do this fee without a web site too). Then you play the audio and move the little bars to decide when SlideShare advances the slides. Voila! Webinar.

Easy peasy lemon squeezy – now who’s going to join me?

Posted by: Kelli Brown | April 16, 2009

One to watch

Ever meet someone who really made things click for you? Someone you couldn’t help but learn from? The type of person that made you feel a little smarter just because you knew them?

For me, that guy is Ohad Inbar.*

Ohad is a usability specialist. But unlike many UI people, his focus is on the “incidental user,” the people who have interfaces inflicted upon them. I think that one of Web 2.0’s major effects was a shift in control to users who previously lacked a voice. Ohad’s research is valuable now, but I think it’s going to become even more valuable as our average everyday user becomes more tech savvy.

Ohad has a remarkable ability to see things in a new light – a real innovator. You can imagine how excited I was when he started a blog. He’s at the top of my list of people to watch and I hope you’ll join me.

* His wife, Rachel, is also a genius. We call her Rachelpedia in our house. It’s a two for the price of one deal.

Posted by: Ben Mansheim | April 6, 2009

A Handful of Links to Spark Thoughtful Discussion

As a result of implementing the practices of taking 15 minutes a day to innovate (OK, maybe a little longer), I happened upon a few articles that caught my attention as related to our quest to reinvent the document. With the economic news being what it is, we are clearly not the only ones thinking about the “next best thing” for our industry. Allow me to introduce these topics for your reading pleasure:

  1. Anne Gentle suggests a number of strategies for us to either keep our fingers on the pulse or to dictate the pulse of technical writing/producing/communicating/community’ing or however else you want to help people to understand the technical information that they need to do what they want.  The links in the article could take some time to go through but are clearly central to our search for improving our services.
  2. Tom Johnson relates the story of a writer turned video producer whose tranformation occured… almost 5 years ago.  We have been talking about video as an innovation. Well, clearly that ship has already set sail. It’s not too late to join the crew and make a difference with that technology, but when is the next cruise and where will it go?
  3. In an more general approach to innovation, Alice Rawsthorn writes on that innovating innovations has already been innovated with many innovative results. What I get from this article is that innovation cannot just be done for its own sake. The real key is to find what people need and give it to them.

I would like to add one other point. I agree with the sentiment that we, technical communicators located in Israel, have a value that cannot be overshadowed by our colleagues in any other location, be it the US, India, South Africa or [name one]. I would like to encourage local practitioners to follow and comment on the more popular blogs in our field. This small effort can improve our understanding of what is going on in the rest of the world and hopefully develop new ideas that we can implement.

!חג שמח

Posted by: shoshanak | March 30, 2009

Your Work Environment Just Changed

How do I respond when management decides to change from a waterfall style of project development to an Agile environment?

Back in the old days, when I was just starting out as a software engineer in a large defense contractor company, I learned the top-down and bottom-up approaches to software and system design and development. We were dealing with large collection systems made up of major subsystems like the forward link and the return link, and all the supporting network management system structure. The white paper describing the general approach was followed by requirements definition. Then high level and detail design of the subsystems was created, along with the necessary sign-offs along the way. Development started after signoff. Unit test picked up during development, but integration only started after unit test ended. System testing ran over the entire system, and then we sold off the project to the customer.

When I moved to Adobe, then a small software company, I brought with me many of the good engineering practices I learned. At that time the engineering team was small. An open door policy led to many adhoc meetings taking place in and around doorways as people passed by. Design was structured – all the engineers came from great companies like Xerox-Parc. They all knew the “right” way of doing things, but there was no time to take the “right” steps. Somehow  I adjusted to much shorter product-to-market lifecycles, and learned that sometimes the waterfall method just didn’t work. In fact, it became very clear that the waterfall method could actually cause us to lose a market advantage.

I lost touch with all of this when I retired from technical life to pursue a family. It wasn’t until a few years ago, when I came out of seclusion, oops, I mean retirement, that I encountered Agile. What we had been doing at Adobe now had a formal name. But to me, it was still only in the context of software/firmware development.

Today I work as an engineering technical writer. I hope to encounter situations where I can test out my response as a technical writer. These are the areas I think are important for writers to consider:

1. Writers must become recognized stakeholders from the start. Anyone tasked with documenting a system must embrace and defend being involved in the project from the day of its inception. We writers must contribute to the stories forming the basis of development.

2. Writers must become expert users of the project under development. If the target audience is another system architect or a firmware engineer, or an expert field engineer, or a savvy private person, we must be able to step into their shoes and write their story. We fail in our task as the writer if we don’t put forth the voice of the target audience in the stories that make up the sprint.

3. Writers have to change the writing paradigm. Instead of publishing almost finished manual drafts, we must publish small chunks of information. To do this, we have to come up with stories of a suitable size for a 2-3 week sprint. And we must identify what physical resources and what personnel resources are needed to complete the writing within the sprint.

4. Writers must be physically near team members. Because the sprints are time limited, and the documentation is held to a minimum, we must be in physical proximity to the other members of the staff. During a sprint the team meets everyday. This means we must be on the premises every day. Heads up! This limits the amount of time we can spend off-site.

5. Writers must create “portable offices”. The burden of contract writers can be a logistical nightmare for the hiring company; we must develop our own portable office environment. We have to be able to work in small spaces carved out of the already limited space in the company. We have to be ready to bring in our laptop with all the supporting software needed to do the job. For special cases, we must be adept in installing and removing software as needed.

This is just a beginning of how we must innovate as the world changes around us. Many people responded on various LinkedIn lists about their response to the change. Everyone who responded agreed – an Agile environment is exciting and stimuating. There is no time to get bored. And everyone said they preferred the Agile enviroment over any other environment in which they have worked.

Posted by: Kelli Brown | March 25, 2009

Little Red Riding Hood: Technical Specifications

This is brilliant. What’s your first reaction to it? I’d love to hear it in the comments.

Hat tip to Rachel Inbar for the link via Alex Levy.

Posted by: Yisrael Woolf | March 25, 2009

Inspiration and Brainstorming

Following last week’s meeting on innovation at Check Point, read on for a few brainstorming ideas. These ideas were inspired by various meetings, conversations, blogs, Facebook posts, and comments on my previous posts. Thanks to everyone who has taken the time to inspire me.

Get your creative juices flowing and join the fun: Comment here, join the discussions on the Innovators Wanted – Pushing the Envelope in Technical Communications Facebook group (, join the Innovators Wanted LinkedIn group, or do them all!

Kudos to Kelli for setting up these groups.

To glimpse the kind of breakout thinking that documentation professionals need to start adopting, take a look at these two amazing videos:

First, Microsoft’s glimpse into the future of technology:

And now, for a different twist, get wowed by Pattie Maes & Pranav Mistry: Unveiling the “Sixth Sense,” game-changing wearable tech:

And consider how technical communicators can apply learning principles that Head First uses in training materials:

Now, let the brainstorming begin!

On-line user groups: If you can’t beat them (which we should NOT be trying to do!!!), join them! Let’s initiate them, and then seed them with FAQs.

Corporate blogging: Let’s be the prime movers to get the information that users need into the blogs.

Wikis: Allow users to put in content that they find useful. Our niche? Moderators, reviewers, approvers – and primary contributors!

EPSS (Electronic Performance Support Systems): Provide comprehensive information that pops up when the user rolls over the item.

Twitter: Answer questions by sending the web address that has the answer.  Easy to keep under 140 characters!

Video: Want examples using animation and voice-overs? See the video on (Tip: log out of Twitter before clicking) and the Jonathan Jarvis example in Kelli’s Alternative Documentation post.

Audio: Provide human voice (actual or automated) explanations to supplement text or as an alternative to it.

Embed animation, video, and audio in traditional media such as Help and PDF.

IDE (Integrated Development Environment): Adopt usability ideas from the IDE programming world. Examples: Have correct values appear automatically based on initial user input. Color code different kinds of information.

In summary: Some of the ideas are not new. Let’s make it a habit to consider one new idea whenever we start a documentation project.

Then let’s take it a step further: Improve and expand the methods that are already taking off.

And let’s go all the way: Break the barriers to the next generation of user assistance.

What will that look like?

You tell me!

Older Posts »