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

Question

Summary

Starting from the position that -- with modern web delivery -- the line between technical communication and marketing content is fading (as all the content is available to business and technical readers via search) and it is desirable to have a more consistent tone across the organization... how can I (as an experienced technical writer) work with the "market-y"-leaning folks to make that tone more consistent?

Considerations

The idea is to minimize a jarring difference in tone. We're already unifying product terminology across communication channels.

I'm not looking for reiteration of "know your audience." I'm trying to understand/reach my modern audience.

In the interest of making a case... I'd especially like some help describing the traditional differences between marcomm and techcomm, beyond than my default reaction to marcomm as "fluff" and "rah rah" and "jargon-filled." There are legitimate reasons marcomm has traditionally written the way "they" have, I'm just not fluent in them. I want to build bridges, not walls ;-)

Typical scenario: The "front of house"/marcomm type colleagues want to expand on introductory material in technical doc, because potential customers might come across the technical content and need some context and market placement.

Related to: Should software product release notes be in marketing voice or technical voice? (software documentation)

Answer 1

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.

Answer 2

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.

Answer 3

This is tough.

I tend to have 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 they aren't necessarily as high of stakes as they feel sometimes.

I bring this up because sometimes I bring my frustration about these misunderstandings into marketing-related conversations. Despite that probably not being 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. If that's not a specific goal, however, you might be better off going with what will convey the target 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 ultimately 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 audiences 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.

Answer 4

The target audience is key.

If you know who you're writing the document for, and it cannot be everybody, or the customer all the time, you also know what level of tech/market communication you should have.

Take a project proposal as an example. This document is intended for the customer. It's written to help them decide whether they want to purchase the project or not. The goal is for them to understand what the project will produce, e.g. in the shape of a software system.

I've seen this type of document full of technical blah-blah-blah (e.g. SQL queries)... And what happens? The customer starts skimming, convincing themselves they'll get what they want, and the supplier knows what they are doing... and of course, the customer misses the details in the proposal, and project rot ensues...

On the opposite end, you Google for SQL server INSERT syntax and get page after page of how incredibly great SQL server is and rah-rah-rah... (You install MySQL... almost...) And yes, this was several years ago, and hopefully the result of bad SEO not bad document writing.

The thing is, if someone is in need of low-level technical information, marketing texts will stand in the way of them (the customer's employee) doing their job.

Knowing, and deciding, who the target audience is and communicating with them in a way that doesn't offend, belittle, hinder or numb them is a sign of good communication skills and it will also be a surface marker of your company's overall quality...

And yes, if you're dealing with a smart customer the managers, technicians, and every other relevant person in between will be asked for input before a decision to renew the contract/purchase more...