Posting news on the web

People write poorly on the web, everyone knows that. In my job, I'm exposed to surprising amounts of it, including bad writing from vendors - commercial and open source - who have every reason in the world for not writing poorly.

Look. If you want to get your point across, write well. It's easy, as long as you remember who you're writing to: "Someone else."

That mythical someone else has not been following your product from initial inception and requirements analysis, or even from minor release to minor release, and not even from major release to major release. Your audience has no clue what you're producing. People who don't fit this profile are outliers, nothing more.

When you write about your product, you simply have to give something that the uninformed can understand. It can be simple, even incomplete - "This is a web services engine" - but it has to give the reader something to hold on to. After you've set the stage of what it is, you can then describe why you're announcing it, what makes it relevant.

This web services engine is different than the rest because it automatically discovers resources you might want to make public, and allows you to configure who, if anyone, can access it, and how they can access it.

While that sentence is too complex - hey, I wrote it, what do you expect - it's clear. It's talking about web services, it says what differentiates it. "Someone else" has a chance of understanding what you're talking about.

"Why" is important, too. Why do I want a web service engine like that? It might be nice if the vendor says "This is a quick summary of the problem we're trying to solve," in clear english, for the techno-illiterate (which means, mind you, someone not well-versed in the problem domain, not someone who, uh, doesn't grok tech, eh.)

If you answer what and why, you've done the lion's share of your work as a news poster right there.

"Who" is important, as well, but it's also easy to put in:

The Whosit project has released Wheresit Web 1.0, a web services engine. This web services engine is...

If you've grabbed readers with what and why, along with who, then you finally want to get into where, how, and when, with where and how being interchangable. At this point, you have people who are interested, so you want to give them some explanation of what you're talking about, to clarify you vision of the "what" and "why." You need to flesh out why their interest is justified.

Wheresit works by examining your public services exposed as stateless session bean endpoints, and then creates WSDL for each one. An administrator can then assign groups to each WSDL for public exposure. The Whatsit plugin then allows conversion of the SOAP endpoint to an XML-RPC endpoint or, in some cases, even a REST endpoint.

I'm not a writing coach, but I can't begin to tell you how difficult it is to really try to understand all these announcements - all because their authors are forgetting some simple third-grade writing rules about answering some basic questions in writing.

Your readers aren't stupid - it's okay to skim past details. Nobody wants to know your entire organizational structure, in an attempt to understand the "who" question, but it's important to at least frame everything properly for context. It's also okay to skip tedious details that only you are interested in (such as "this version, we reformatted all 1182 lines of code in the Fuggetaboutit class!")

Avoid this stuff and you're left with jargon and buzzwords. Nobody wants to read that. Nobody cares. The whole point of a news posting is to make people care.

Do it right.