A Touch of Class

f. rainne
2003-10-30 – 2003-12-08

Content and Hype, or, English Composition for Marketers

Since the launch of Mozilla's new courtship of end-users, marketing hype has slowly infiltrated the hapless mozilla.org website. Rather than eschewing marketing obfuscation, our eager advocates embrace it because, of course, this is progress! Jwz was referring to technical documents, not marketing ones—marketing is supposed to be hype; his guidelines therefore don't apply. Or so one would assume.

Eschew marketing obfuscation.

Actually, this is some of the best marketing advice I've ever read. Take a closer look at the sentence. It doesn't say "Eschew marketing"; it says "Eschew marketing obfuscation."

One of the things that people seem to like best about the existing content on mozilla.org is that it is written by people, for people, without bluster or self-promotion.

Are you excited about this product? Yes? Then show it! The most convincing marketing is by people who are enthusiastic about what they're promoting. But don't chatter at me with repetitive nonsense, don't tell me that it's the greatest thing since the kitchen sink, tell me why it's great. Let me see for myself why it's so worthy.

When describing something, don't tell people how great it is. Don't tell them how useful it is. Tell them what it does. Tell them what it's for.

In other words, don't tell me how great it is. Tell me how it's great. Don't tell me how useful it is, tell me how it's useful.

Don't use buzzwords. Instead, say what you mean. Never use a long word where a short one would do. If it's possible to cut a word out, cut it out.

A visitor is there to get information, not words. Don't pad it out with fluff. Don't replace it with hype. Fluff just takes up room, and hype is not fulfilling. It wastes the reader's time and dilutes the message you're trying to send. The visitor wants to know why this product is worth using—that's what he's here for—but he doesn't want to wade through marketing BS or irrelevant details to figure it out.

First Impressions

Let's take a look at an example of what not to do:

It sounds like "we" thinks it's a fantastic group of people. They're innovators and producers, advocates and partners, a community of developers, and look at all the powerful features they've implemented in all their advanced products!


The only thing I've learned about "us" is the kinds of products it makes (which I could've figured out from the Products pages), what features they have (which I could have also learned from the Products pages), and the fact that it's an open source project (useful enough, since it's hardly mentioned anywhere else on the site). I haven't learned anything about the organization itself, which is ostensibly why I'm reading this page in the first place.

The description of Mozilla 1.5 excellently summarizes the product's most noteworthy features—but it belongs in the Mozilla 1.5 product description page, not here. Here it only increases the sense of unrestrained advertising: "just keep plugging the product line".

Of course, this is all assuming I read the doc. By the time I've read the first paragraph of this marketing riff, I've already formed a judgement about the document and how I should read it: it's mostly useless hype, so I'm only going to skim it to get an idea of the general scope and gist. My impression (and therefore my method) doesn't change further down. I'm catching the headings, the linked phrases, and a surface impression of the contents, mainly some babbling about products and features. The buzzwords in the introduction are all conveniently highlighted for me, no doubt so I can compare word lists with mozilla.org's competitors(?) later...

The end result? Any real information buried in all this marketing obfuscation (such as the link to the mission statement) gets lost, and I've come away

  • without having learned anything useful about the Mozilla organization and
  • with an impression of the organization as an empty collection of buzzwords.

Needless to say, the document has utterly failed in its purpose.

grade: F

Answering the Question

So it doesn't look like I'm unfairly bashing this one document, let's look at Ben Goodger's "Why use Firebird" article.

This document gives a very comperehensive list of Mozilla Firebird's features — there is a lot of good, solid content here. However, there are too many details. The article is for presenting Mozilla Firebird's features, not for explaining, in detail, how to use them. Also, there is some marketing fluff that could be trimmed out.

grade: C

Feature descriptions like these should be "short, sweet, and to the point": enough to demonstrate to the reader what the feature is and why it's useful, but not enough to waste his patience or lose his attention before the next heading.

So what happens when a marketing doc meets an editor?

This trimmed-down version is based off a draft Firebird home page by Tristan Nitot. I've just lifted more content from Goodger's article and the current Mozilla Firebird home page to make it more complete (and fixed a few minor grammar and style problems).

grade: borderline B+/A-

Rhetoric vs. Eloquence

To get into the higher A range, writing must have eloquence both in thought and expression.

Compare these three Tabbed Browsing blurbs.

I won't go through a complete line-by-line analysis, but let's look at how the original description has been improved:

The "trimmed" version has cut out a lot of useless verbiage:

The result is less than half the length of the original and much more focused.

Cut-n'-paste, however, cannot compensate for missing logic structure. While it's no longer necessary to sift through the excess prose, the poor ordering and connection of ideas forces the reader to infer ideas that ought to be clearly presented.

The Mozilla Firebird homepage version doesn't have this problem. With explicit logic but without explicit detail, it tells me

  1. what tabbed browsing is
  2. how it's useful
  3. why I care

Besides the fluency of thought—and most likely because of it—the paragraph flows fluidly at the rhetorical level as well.

The details make the difference between the good and the great

A little careful tweaking can make the last one even better:

Open multiple pages in a single window and load links in the background — tabbed browsing is a fast and convenient new way to browse the web. By holding down Ctrl when clicking a link or using your middle mouse button (if you have one), you can open links in background tabs while you read a web page and continue to the links when you're done. Pages are already loaded when you need them, making the web feel faster even over slow connections.

What I changed and why:

In summary

What should you take from this lesson?

Finally, hats off to the authors for providing such excellent examples. Please don't kill me for using them... >.<;;

A professional attitude means being honest and straightforward: it means presenting yourself well. It does not mean pretending to be what you're not.