Tech Writing Doesn't Equal Science Fiction

For the love of all things decent and true, in whatever you do, don't write fiction in a technical document. In other words, document only what exists.

Some might want you to create something that's called vaporware in documentation. Vaporware is touting a feature or features in a software, or even software, that doesn't yet exist. There's also a chance it may never exist.

If an SME or even management tells you to write or document that doesn't yet exist, please gently, but firmly tell them no. Just plainly tell them, "until we have an actual feature, product, or whatever that is actually in existence, let's leave this out of the technical documents, especially user manuals." I have run across a few SMEs who wanted to document steps or entire sections in user manuals that still in dreamland.

I am picking on rare cases where people will try to cajole you to write vaporware. Most SMEs have better sense than that. But if the rarities do try to pressure you to write science fiction, then you respond with some reasons why.

Credibility Gap

Losing credibility should be reason number one in avoiding vaporware to show up in your documentation.

If you put out some documentation that should be considered creative writing, the customer will lose faith in your product(s) and even lose faith in the company itself.

If a customer is trying to use a certain feature in a software and it's not there, imagine the frustration and confusion they might have. And then their frustration and confusion becomes skepticism of your company when they realize nothing that's written exists.

Not to mention, this is cheating the customer. They paid for a software or product. It's implied that all features are present. (Now whether it works properly is different story all together.) If there are features in a document, they had better be there.

If you're having a hard time understanding this, switch the roles around. Imagine you're the customer. And you bought furniture to put together. Then, you find out half of the parts listed in the manual were never made. Imagine how you will feel.

Customers will speak out

Before I was a technical writer, I worked in food service. I was told by the store manager, while training to be a manager myself, that if a customer has a bad experience, they will tell ten others, on average, about their experience.

Now this was before the Internet became available to the public and way before social media. Imagine how far news of bad customer experience can spread. Things go viral all the time. Let's hope a company you're working for doesn't go viral negatively because they were too lazy or dishonest to actually to create the features or even the product itself.

Now if a company has a total disregard to what I've said, then in my humble opinion, they shouldn't exist--like vaporware. Instead, they should evaporate like all other bad businesses do.

Easy to forget vaporware is there

You might hear a defense of documenting vaporware that's goes along these lines: just put this in anyway because we'll go back and create the features. With all the other things you have to keep track of during a product release, it's to easy to forget vaporware is in your document.

In my early days as a technical writer, I've had SMEs tell me to put vaporware in. So I put them in and guess what happened: the document went out with the product because we never got back to it before release time.

It wasn't until I put my foot down to document only what exists that the practice of documenting vaporware evaporated at a place I once worked at.

An exception to document the not yet

There might be exceptions to documents that don't exist like a proposal internally between departments, programmers, or engineers, so that they can get an idea of what to create. But for ALL external documents that are going out to customers, it should be big NO.

Serious considerations

If you work at a company where vaporware appears in your documents, I would everything possible to stamp it out and reject any spurious material that comes your way.

If your company's management or leadership is okay with vaporware, encourages it, or even demands it, then I would quit as soon as possible. If you're a contractor, then I would stop doing business with them as soon as possible.

If the company doesn't care about its reputation, then you should, at least, care about yours.

Now if you're okay with documenting vaporware, then my suggestion is to seriously consider writing science fiction. At least with that type of writing, you will have more credibility.