How can I make a case for toning down the "rah rah" marketing tone around technical content?

I believe the key question to ask yourself - and your marcomm colleagues - is the aim of each piece of documentation you are producing.

Using your example, you can have two kinds of introductory material for your product: the why should I use this and the how do I start using this.

For the second type, you're dealing with "pure" techcomm - instructing a user who has already decided on your product. They need no more cajoling, they need specific information as to why and wherefore. There is, in my opinion, no place for marketing-speak here and you should stand your ground when discussing this with your marketing-minded colleagues.

With the why should I use this kind of introduction, the situation is more complicated. An intro like this would serve a dual purpose: to inform (e.g. about specific features, technical requirements and whatnots) and to convince ("use us because we are awesome").

I believe the best solution (if your content structure allows) is to clearly distinguish these kinds of texts. For example, at the start of the "mixed-type" introduction you can include a clear link: "See this for a technical overview of the system and its features". Preface the technical introduction with a "Still not convinced? See 7 good reasons to start using Product X" and link to the marketing-y part.

Marcomm has, as you called it, "legitimate reasons" to not always be 100% truthful - absolute about the product does not always sell. By its nature, marketing may stand in opposition to the fundamental rule of technical communication: to tell the truth, the whole truth and nothing but the truth about your product.

posted almost 7 years ago

CC BY-SA 3.0

System‭

3226 reputation 147 215 553 0

I am both a technical writer and marketing writer (I am a PhD with a background heavy in CS, Mathematics, statistics and mechanical engineering, with 40 years experience).

I have written manuals, spec sheets for products, instructional materials and advertisements for products and services, including brochures and globally published ads that have been successful.

To me, marketing is not fluff, or rah-rah, or jargon-filled. I can avoid all of that and still sell product. In my view, the point of marketing is to convince a potential customer with a specific problem that you and/or your product or service can solve their problem, without lying to them or trying to con them into buying something they do not need.

I will agree with your front of the house colleagues, and I will note a common maxim in sales I learned 40 years ago is 100% true: Nothing happens until there is a sale. We can develop the best widget ever made, but if we don't sell any, we've got nothing to do, and widgets don't sell themselves, somehow and in some way potential customers with a real pain that can be relieved by our widget must find out we have it, and what it does, and how it relieves their pain, or they won't buy it.

Any channel by which they can find that out is a valid channel to be addressed by marketing, including your technical documents if they might find them by a search.

The case to be made requires you to distinguish between "rah rah" writing, and legitimately pointing out the bigger picture about the product and how it helps people with a specific problem.

So (making this up) maybe your A/D sampling chip can oversample at 100KHz and this lets the hardware synthesize a more accurate 44.1K samples per second. That would be a "fact", but marketing may want to emphasize the consequence of that fact: A cleaner audio signal with fewer aliasing artifacts or harmonics, suitable for higher quality digital music, sound effects and soundtracks.

That is a problem people many people might want solved, and searching for spec sheets, this tells them yours is the A/D sampler they want. Finding out this is used by your X, Y, Z clients may send business their way and ultimately increase your orders.

I personally don't like anything I would characterize as untrue or empty rhetoric or misleading, but I don't mind covering every opening that might reach a customer with a layman's explanation of what our products do and how they help.

I am not defending marketing by saying "we are in business to make money," I sincerely do not believe that. It is a far more difficult proposition in my view, we are in business to satisfy customers at a profit, without exploiting them, our employees or society at large. And that is so difficult, every avenue of recruiting customers, without lying to them, is worth exploring.

posted almost 7 years ago

CC BY-SA 4.0

Amadeus‭

3156 reputation 2 1399 613 37

This is tough.

I tend to have what a view that I think is fairly close to yours and I think it's often difficult to argue for more accuracy without coming across as pedantic. I think that are a couple of realizations that helped me with this, though.

Being deceptive is bad, being vague is okay.

As a person that cares a lot about the details of processes I am often concerned about people using terms that I view as "fluff" because they perpetuate misunderstandings or incomplete understandings that I would like to see cleared up. However, I think it's important to realize that using commonly used terms that have a colloquial understanding isn't being deceptive. It might be intentionally ignorant or pandering, but I they aren't necessarily as high of stakes as they feel sometimes.

I bring this up because sometimes I think I bring my frustration about these misunderstandings into marketing-related conversations. But that's probably not the right time to have that battle. If your goal is to clear up a misunderstanding with whatever you're putting out, then being careful about phrasing is important. Otherwise, you might be better off going with what will convey the idea most efficiently to consumers without getting caught up in qualifications. Your more technical documentation is the right place to address that and be more clear about what is meant.

I don't love it, but I think this perspective helps me choose my battles more effectively.

Summaries/introductions don't have to be technical.

This is something else I had to fight against a bit in my head but after a couple of occasions where I wanted a less technical description and couldn't find it I think this is where I've landed and what has come to feel more natural.

Oftentimes, getting the business context for something can be very helpful early on in documentation. Overly flowery language might be confusing or distracting but having an introduction that "sells" the upcoming content can be a good way to have documentation that not only serves multiple purposes but also reminds technical people of the outward goal of the thing being documented.

In particular I've run into cases where I was reluctant to add something to a component until I realized that to a client it was very nearly the same functionality or at least almost the same use-case. While marketing language can feel out of place in a setting where things get technical, it can also be a nice reminder that the technology exists for business purposes.

There's certainly gray area here but I think this mindset helps create a better environment for compromising on what content is appropriate.

Beyond that, I think starting with points like maintaining the consistency of tone is good. But where you have trouble making headway with those arguments, considering one of the above compromises (e.g. "I'm okay with this being somewhat vague but right now I find it deceptive") may help you find common ground.

posted almost 7 years ago

CC BY-SA 3.0

thesquaregroot‭

25 reputation 2 2 4 0