: Re: How can I make a case for toning down the "rah rah" marketing tone around technical content? Summary Starting from the position that -- with modern web delivery -- the line between technical

@Hamaas631

Vote Up Vote Down

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.

(0)

Login to post a comment!