Most days, I straddle the Berlin Wall between product development and marketing. I used to work amongst the programmers as a technical writer. At Capulet, we don’t do software documentation anymore. However, for a lot of our clients, we’re the Checkpoint Charlie between the people who make stuff and the people who promote and sell stuff.
Seth Godin links to Kathy Sierra’s thinking about why “marketing should make the user manuals”:
Why do so many companies treat potential users so much better than existing users? Think about it. The brochure is a thing of beauty, while the user manual is a thing of boredom. The brochure gets the big budget while the manual gets the big index. What if we stopped making the docs we give away for free SO much nicer than the ones the user paid for? What if instead of seducing potential users to buy, we seduced existing users to learn?
She also provides a graphic illustrating that marketing material is ‘glossy, slick, colourful’ while manuals are ‘plain, dull, black and white’.
This is an incredibly wrong headed idea:
- The user has already bought the product. They want to know how it works, not why it’s good. Often the people using the product are not the people who bought it. They don’t care why it’s good. They just want to know how (not why) it will make their lives easier.
- Seth Godin said it best: all marketers are liars.
Marketers are trained to obfuscate, exaggerate, denigrate and spin. Those are useful talents, but not when you’re trying to explain how things work. - Of all the software marketers I’ve met, only a small fraction has the technical background to thoroughly understand and explain their products. Go ask some folks in BEA’s marketing department how to, say, deploy a message-driven EJB, and see how they do. This isn’t a criticism. Most marketing doesn’t require an in depth understanding of the thing you’re promoting. It helps and is something you should aspire to, but it’s also pretty uncommon.
- Technical writing is a skill set that’s significantly different than marketing. In additional to the technical know-how, you need industry-specific tool knowledge, an understand of usability, instructional skills and so forth.
There’s a reason why words like ‘glossy’ and ‘slick’ have negative connotations. Because they imply shallowness, which isn’t something you should aspire to in a user manual.
It’s hubris to say, as Kathy does, that “shouldn’t we be using all that graphic design and pro writing talent for the people we care about the most?” Ah right, so there hasn’t been any design or ‘pro writing talent’ applied to that area yet? And marketers are the saviours? Right.
User manuals get a bad wrap because companies don’t devote enough resources to them. That money should be spent on thoughtful tech writers, trainers and support personnel who can make compelling training and support material. It shouldn’t be spent on applying lipstick.
In truth, manuals are frequently an admission that by a company that they didn’t design the product well enough. Do you really need a manual for an iPod? Check out the help system in the Apple OS. It sucks. Why? Because it’s so rarely referenced by the user.
The people who sell the product shouldn’t be writing about how the product works. Why not? Let’s revisit BEA. I’m not picking on them, they’re just the first company with a complicated product offering that sprang into my head. Visit the product page for BEA WebLogic Server. Presumably marketing wrote it. The first paragraph of text reads:
Your business can’t afford to have your application server fail. BEA offers an application server built for mission critical applications and service-oriented architecture (SOA). The proven Enterprise Grade Kernel keeps your applications up and running even when deploying a new version, changing the server configuration or failing over within or across data centers.
Then check out the introduction in the manual for the latest version of BEA WebLogic Server:
BEA WebLogic Server is a scalable, enterprise-ready Java Two Enterprise Edition (J2EE) application server. The WebLogic Server infrastructure supports the deployment of many types of distributed applications and is an ideal foundation for building applications based on Service Oriented Architectures (SOA). SOA is a design methodology aimed at maximizing the reuse of application services.
One sells. The other tells you what the product is and does. Having already purchased the thing, which would you rather read?
UPDATE: I believe this Dilbert cartoon expresses my sentiments nicely.
DarrenBarefoot.com 
Perhaps you should read Seth’s book before you make this claim:
Seth Godin said it best: all marketers are liars. Marketers are trained to obfuscate, exaggerate, denigrate and spin. Those are useful talents, but not when you’re trying to explain how things work.
In 35 years of working within the field, I never met a marketer trained to do any of those things. Some do but they seldom last long, because doing so harms the brand and sales.
Kathy may or may not have identified the correct department to write user manuals but she has described the correct skills. They include the ability to write for the customer, the ability to create concise copy and the ability to create readable design and layout.
Your interpretation of her post was dramatically different than my own. I didn’t take her post to mean that she was hoping the marketing big-guns would start putting together the user manuals to better spin the product, but to use design and copywriting skills to better educate the customer to help make them a poweruser, and eventually an evagelist.
Great design skills are useful for far more than just marketing.
Lewis: I didn’t actually mean to imply that Seth’s book says that “marketers are trained to obfuscate, exaggerate, denigrate and spin”. Those thoughts are my own. It’s a little awkward in that bulleted list, but I inserted a line break to separate those ideas a little more.
You’re right that writing user manuals include the skills you describe. Every tech writer I know has them, plus a whole lot more that are more important.
Brian: I agree that ‘great design skills are useful for far more than just marketing’. Companies should spend more effort on making manuals more usable. Printing manuals on ‘coated silky paper’ does not, in my opinion, improve usability. In fact, most people like to write in their manuals, so it probably reduces usability.
Darren,
Thank you for your reply. I wish you could meet the marketers I have had the pleasure to work with. We take great pride in telling the truth 100 percent of the time, as clearly and as concisely as we can. Every prefession has bad actors, and Marketing is no exception.
Technical writers are, as you say, more than capable of performing the job. I wonder, however, how many high-tech businesses employ them. (The one I worked for did not and would not in order to cut costs.) I have two shelves full of user manuals that are dull, overly wordy and totally lacking in layout that would make them easier to read.
Sort of makes one wonder how many high-tech businesses operate without writers and graphic designers.
I think there were always be differences of opinion here. Depending on your personality type, you might prefer the long-winded analytical descriptions and jargon, or at the other end, you might be best served by a more Ikea-esque manual with strictly images, no text.
And some, like me, can handle a bit of imagination, humour and a even a bit of hyperbole in a product user-guide.
So in the spirit of bettering the end-user experience and creating customer evangelists, why not this:
Make a user manual that has left brain and right brain useability. Left-facing pages could contain the details and logic, while the right side could reserved for the “look and feel” fluffiness, marketing speak and all.
Could work, no?
Lewis: Are you saying that you and your colleagues never “obfuscate, exaggerate, denigrate and spin”? That seems unlikely, given the extent of deception practiced in the industry. Don’t believe me? Just go visit PRWeb.com.
Regardless, whether marketers lie is tangential to my point: the people who sell the things shouldn’t explain how they work.
Darren: I have had similar experiences with the marketing department in companies I’ve been working for.
They beautify the product. Tell half truths… and lies when it comes to number of employees and money is involved. Especially to journalists.
I think that the logic employed is something like this:
Marketers care about customers. Manuals are for customers. Therefore Marketers should write manuals.
The fallacy should be easy to spot. Try this one on:
Socrates is a writer. Socrates is a marketer. All marketers are Socr^H^H^H^Hwriters.
I think there is some common ground here between what Kathy is saying and what Lewis is saying.
Kathy is saying “take some of the resources from marketing and put them into documentation” (be they budget or expertise). This will make better manuals.
Lewis is saying “let people who know how to write documentation write the documentation, don’t let the engineers do it (i.e., more, and more appropriate, resources for documentation).”
And I agree with Darren—marketing writing and technical writing are very different things. Just because you can do one does not automatically mean you can do the other.
Manuals do not have to be beautiful. They do not need to be glossy or slick. They don’t even need the best layout in the world (though it can help).
They just need to enable the user to find exactly what they need as quickly as possible, explain it as simply and in as few words as necessary, and let them get on with more important things.
Darren, you made a lot of great points, but I think most manuals are anything but page-turners. If users aren’t turning the pages, they aren’t learning. No matter how motivated users may be on why they SHOULD read the manual, for a variety of reasons, they just… don’t. Most of those reasons can be fixed, but not by expecting users to take responsibility and RTFM.
Instructional designers know that learning requires motivation, but most traditional instructional design models do a terrible job of specifying exactly how that motivation is supposed to happen (performance objectives are not enough). Most technical writing–regardless of how clear and appropriate–does not address the main problem of making the content *compelling*. We know how to appeal to the reader’s logical mind, but not how to connect with their legacy brain, and for that… we need to add in those other skills that many marketers and advertisers and good designers have… the ability to reach past the brain’s crap filter, catch their interest, and most importantly–get them to keep turning the pages!
Most (obviously not all) manuals are not engaging the reader’s brain. That’s a problem, and if marketers can *help* make the actual learning content more compelling, that would be a big step forward. I agree that this has nothing to do with motivating users on why the PRODUCT is good (you’re right, that’s no longer an issue). This is about motivating them on why LEARNING MORE is good. It’s about using the skills that help encourage someone to pick up and read a brochure, and apply them to encourage users to pick up and read the manual (or at least the getting started,learning, and other non-reference parts).
As for your BEA example, I actually think BOTH of those pargraphs suck. True, the second one does a better, more accurate job of describing what the product does, but neither of these are the least bit compelling. And I haven’t even talked about memorability… many marketers and advertisers have a lot to teach the rest of us (tech writers, like me) about making things memorable and let’s face it–the clearest tech manual in the world loses effectiveness if the reader has to keep reading the same parts because it didn’t “stick” the first time.
Anyway, I do think you added a great deal to this conversation, and made me realize a ton of places where my post was weak or said something I didn’t intend. And you got us all to think more deeply. YOU have the skills to make things compelling, Darren. If more people writing tech manuals had your ability to be engaging, there’d be a lot more happy users (and a lot more tech support folks out looking for jobs) ; )
Some types of information are simply not entertaining. It’s not easy to add zip and flair to drawn-out procedures for configuring complex data warehousing software.
It’s not the skills we tech writers lack, it’s the time. Too many companies fail to understand why it should take longer to write a book than to read one.
And to complicate matters, many companies make late and radical changes to not only how the product works, but the entire purpose and target user. This makes it difficult to write manuals that gently guide readers along the path from total ignorance to expert status.
Hmmm, I seem to have recently developed a defeatist attitude. Maybe I’m working for the wrong company…
I agree with you Darren. The most important aspect of a manual is ease of use. No one will read an instruction book from cover to cover; they might read the introduction and the getting started sections, but more likely than not, they won’t delve into any other part of the manual until they’re stumped. At this point, two things must happen:
1) The information must be easily found. This is where a good table of contents, a comprehensive index, and a well-designed categorization/section system comes up. If I’m having trouble figuring out how to download pictures off of my camera phone, I shouldn’t have too much trouble going to a specific page in the manual for that particular task.
2) The information must be easily understandable. This is especially true for consumer products. Eschew the jargon and put it in a language that Joe Public can understand and put in practice.
Nowhere in the equation does the writing have to be necessarily compelling, engaging, or even interesting. Technical writing is, in my mind, for “functional” purposes only, whereas marketing speak should be fun, engaging, thought-provoking, and so forth.
I understood Kathy’s article in the context of a previous one: Are your users stuck in “P†mode, in which she argued that most manuals focus on the wrong thing.
Most manuals focus on how to operate the tool … not on how to achieve what you bought the tool for. For example, the high-end digital camera that you bought tells you all about how to set shutter speed and focal length … and not a word about why you would actually want to do that, when you will want to adjust those parameters, and what effect it will have on your photos.
In other words, the manual is about the camera, not photography. It’s about the product, not the activity.
That’s the context in which I understand her saying: the amount of energy and resources that go into marketing a product should also go into explaining the use of the product.
That just makes sense.
And that’s where marketing can help … because marketing is always (or should always) be focused on the reasons why a person would buy a particular product.
More details here:
http://www.sparkplug9.com/bizhack/index.php/2006/08/30/marketing-and-the-manuals/
I agree with Kathy on one point, I think the second paragraph from BEA also sucks. As a techy, once I see the words “enterprise-ready†a chill goes down my spine, and I think that the marketers have already become involved in writing the manual!
Why are we talking about printed manuals anyhow, that’s not very Web 2.0 is it? Context-based help systems embedded directly into the application is where it is at. I don’t want to have to go to a separate application or find a physical manual to find the help I need, that’s way too slow.
Why not place a question mark on any screen in the application, beside a button for example, which when clicked will present the user with an explanation of what that button does in a pop-up window. Lots of applications are heading this way…
Darren
A lot of this debate centres around a misunderstanding of the term marketing and your focus on practices that Kathy and I and other commenters would describe as bad promotion. Collectively we are talking about manuals being more effective and do not see the route to this as merely handing them over to the lame marketing practitioners to whom you refer.
I’d be interested in your reaction to an attempt at clarification that I made some time ago
http://makemarketinghistory.blogspot.com/2006/08/geek-marketing-101_115529822564302037.html
John
P.S. Re BEA manual, if I had bought the product I would hope that I already knew what it did in general terms at least.
I’ll echo other comments, Seth’s Book is in fact not about Marketers as Liars, but in fact that customers want companies to make them feel good, so marketers tell them a nice story.
It’s an easy read, I suggest you update your post to reflect the innaccuracy and then grab a book for a read!
Excellent thoughts, I do agree, Marketers should not be part of the User Guide creation process~!
It’s not that the “ideas” of marketing and technical writing suck, it’s the actual practice of those ideas. Marketing is supposed to be about connecting people with products or services. It is an educational process designed to help the learner decide if the product will give them what they are looking for. Just looking at a product may not give you any idea if it will provide what you are really looking for. The person may not even KNOW what they are really looking for. The marketing process (i.e. copy) should build trust and say what benefits the product really provides. That is the real purpose of marketing. Of course, this rarely occurs.
The help manual is also an educational process. It continues the marketing process. Now that you know what benefits you want… how do you get them? We tend to think in terms of those benefits. For example, I have written a help manual for a point–of-sales program. I also do the training for that program, so I get a feel for what the user is looking for in the help manual. One benefit they want from the program is the ability to save money by using less labor. What features of the program allow that? How do they get to them? How do they use them? I have had to re-write large portions of the manual to accomodate this way of thinking.
I guess what I am trying to say is that both marketing and technical writing should connect the user with the benefits of the product or service. That is really what they want. They both (should) require a lot of knowledge about the product. Real marketers and real technical writers should not be that different from each other. I actually perform both functions where I work and have to put myself in only a slightly different frame of mind for each function. It is a great perspective and they both compliment each other well.
Not only keep marketing away from the manuals, keep engineering away too. I know this from working in an engineering capacity ( electronic design work ). Engineering shouldn’t write manuals because they take too many things for granted. Things that seem intuitively obvious to design engineers,usually are not for end users. All you have to do is look at the manuals for various EDA tools ( Electronic Design Automation, used for things like schematic capture, board design, and FPGA work )these are written by engineers, for engineers. Some of the these manuals really suck!. Unfortunately, good tech writers really don’t get no respect in a lot of companies, so marketing and engineering colaborate on the manuals, which accounts for so much of the dreck.
Darren,
I think you have mis understood Kathy’s point.
Does the user manual need to look awful to say to the world that it is the user manual?
Can it not look good, Can it not feel good to make a user start to look into it and read into it?
Only when you give an attractive package , a customer will think of looking at what is inside the package.
The ugly look in itself is a put off for me even though a particular manual is superbly written and illustrated.
Unfortunately not everyone in the world is filled with geeks and techies…The majority are normal people who have normal aspirations.
Sometimes taking the trouble to present something is a better, useful manner will only help the end user from scratching his head.
You and Kathy are both right. I don’t think marketing should write the manuals, but please let them dress them up. Yes, I’ve already purchased the product, but I want to continue to feel good about it. Lumbering through a mundane, black and white technical manual screams “we’re just like everyone else” and at that point, all marketers do become liars. You lied to me when you said this product was cool and easy to use. You lied to me about how enjoyable my experience with your product would be. Why do I feel this way? Because you stopped the experience at the user’s manual.
Have the technical folks write it for accuracy then hand off to marketing AND your Learning & Performance group to ensure that even installing, setting up and/or learning how to use your product is just as much fun as you said it would be before I bought it.
“Have the technical folks write it for accuracy then hand off to marketing AND your Learning & Performance group to ensure that even installing, setting up and/or learning how to use your product is just as much fun as you said it would be before I bought it.”
How about running the manual by some of your customers as well? Generally speaking, manuals can be somewhat confusing to some folks because of technical writers & perhaps this could be mitigated by asking users of the product to comment on it (streamlining the way the content is structured).
A secondary issue with manuals is that they generally include *everything* that you need to know about the product. A Top 5-10 list at the front of many manuals would probably increase the enjoyment of many products immensely & reduce service contacts by customers.
While both sides land a few zingers, there is a false premise at work here. Brochures only make salesmen feel good and manuals are written by the technology love-struck! If you have come to rely solely on brochures to make the sale and manuals to retain the customer, then the business is heading for ther dumper anyway. Both Kathy and Darren mean the same thing–deliver an outstanding customer experience–but they are both sidetracked by window dressing. Solve the customer’s problem in the pitch, excecute like a mofo, and put the friggin’ manual in plain English (or your choice of locally-appropriate lingos).
I’ve worked in all of these areas, and they differ considerably. Engineers and programmers must train themselves to think like machines, so they are often bad at explaining how things work to people. Marketers highlight the good, sell the benefit, tell the story, and usually hide the bad. Technical writers explain the background and outline the process. They are all different tasks, and usually require different skills. User interface or interaction designers are another class, requiring both technical skill and human understanding that prevents them from working as engineers, at least on projects where they work on user interface.
I think Kathy’s fundamental point about making instructions and manuals compelling is a good one, although ideally, as much of the product should be self-discoverable as possible. Manuals should tell stories. But they also need to work as references for people who want to figure out a specific thing. Striking a good balance there is hard.
Perhaps a perfect manual would be one so interesting it would be its own marketing material. Griffin’s old manual for Final Vinyl 1.0 used to do that, with its funky ’60s-inspired colour scheme and flower patterns, spunky tone, and easy flow. But that’s simple software, and now version 2.0 has a still-entertaining but much less groovy design. Pity.
Oh, and how could I forget about the stupendous marketing-cum-instructions for Beagle Bros., the greatest software company of the 1980s. If it had materials like that, I’d buy Windows Vista and not even install it just to read them.
I most agree with Derek K Miller, marketing, documentation, and engineering are all separate fields and each has its qualities (in the ideal case). What I want to add is that they should really be working together, not only to harmonize the user experience, but also to cross-pollinate ideas and techniques. I think this was Kathy’s original idea: add the visual appeal used by marketing to improve the user docs. Unfortunately, the larger the corporation, the less likely that various groups speak to each other.
I also strongly believe that “as much of the product should be self-discoverable as possible.” Hopefully, in Web 3.0, we won’t need any manuals, because “it’ll just work.” Mass-consumer cameras won’t need an aperture setting, and you won’t need a course on photography because there will be a “depth of field setting” allowing you to select “subject only in focus” or “all in focus” across all other modes.
However, I believe the whole discussion is moot based on resource allocation (in other words, the real world of corporate struggles). It really boils down to customers not being willing to pay for nice looking docs (not because they don’t want them, but because they were led to believe the product would be easier to use and not require extensive research). I am a tech writer, and I have seen no trend towards either better docs or better products. I believe marketing is favored in corporations because it is composed of ambitious people who know how to promote themselves.
I’m a bit late to the party here, but I responded to Kathy’s post as well.
Bringing marketers in sounds like it could be a good idea, but I’d tend to agree that they would probably write a “ra ra ra” cheerleader manual.
My main point was this — manuals are obsolete. Ok, that’s perhaps a bit harsh, but there are so many other ways of learning: videos, user communities … and instead of bringing marketers onto manual writing projects, companies should find other, better ways of presenting information for learning.
Brilliant topic here, and one that I negotiate daily. Let’s make a manual, put it on an online Intranet portal, and people will download and read it. Bullocks. They want someone to show them every step, they call the training teams daily to have them “pop by” their cubes for 1:1 instruction, and even when you reveal that there is mouse-over instructional text they ask you to just humour them and show how the software works.
Usability is key for software, but for some bleeding reason, and you heard it here first, people do NOT own their own knowledge. I see marketeers (as they’re known in my workplace) fresh out of college, and they can barily manipulate Word. If you recommend they take computer classes, then you insult them.
User-centric design is key, but what is the user willing to learn? Not a sausage.
Keep up the great rhetorical debate!