Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

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

+0
−0

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)

History
Why does this post require attention from curators or moderators?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/33270. It is licensed under CC BY-SA 3.0.

0 comment threads

3 answers

You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.

+1
−0

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.

History
Why does this post require attention from curators or moderators?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/33272. It is licensed under CC BY-SA 3.0.

0 comment threads

+1
−0

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.

History
Why does this post require attention from curators or moderators?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/33274. It is licensed under CC BY-SA 3.0.

0 comment threads

+1
−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.

History
Why does this post require attention from curators or moderators?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »