Primary menu

Aside

Welcome

Hi and welcome!

I’m Larry Czaplyski, a Virginia-based technical writer. I have over thirty years experience working in high-tech companies. I’ve worked in clean rooms, factories, and customer sites installing equipment and making repairs down to the component level. I’ve produced training material and then delivered it from the instructor’s platform. I’ve written countless technical documents. Now, I work as an independent contractor. Keep me in mind when you need an experienced writer for off-site work.

 

0

Types of Technical Writing

Types of Technical Writing

There are two types of technical writing. Of course, I’m only talking about technical writing as commonly practiced in industry. These two main types of technical writing are hardware and software technical writing.

Hardware Technical Writing

Hardware technical writing covers a wide range of documentation. These documents involve handling and working with the physical aspects of a product.

  • Acceptance test procedure - Provides a set of instructions for testing a product before the customer takes possession.
  • Configuration guide - Provides information on how to install and initially configure a module.
  • Design documents - typically written by engineers; however a technical writer may edit or rewrite.
  • Installation guide - Typically includes installation preparation, troubleshooting, removal and replacement procedures, technical specification, connector and cable connections, and power supply information.
  • Job aid - A job aid or help aid is something that allows an individual to access the information he or she needs to perform a task quickly.
  • Maintenance guide - Provides maintenance procedures and guidelines.
  • Operations and maintenance (O&M) manual - Provides information about checkout procedures, diagnostics, external connectors, and field replaceable units (FRUs).
  • Product overview - Most often a marketing document but technical writers can produce these high-level product descriptions.
  • Release notes - Provide information about changes to the hardware.
  • Site preparation - Provides pre-installation instructions.
  • Training manual - Provides instructions on how to use a piece of hardware (e.g., a tape drive).
  • Regulatory Compliance and Safety Information - Provides international agency compliance, safety, and statutory information.

Software Technical Writing

Software technical writing likewise covers a wide range of documentation. These documents involve handling and working with code and software. They can be manuals for non-technical users (e.g., Microsoft’s Word documentation) or manuals for a wide range of technical personnel {e.g., IT documentation) Some typical software documents are:

  • Acceptance tests - Provides procedures for testing a software-based product before the customer takes possession.
  • Administration guide - Provides instructions for managing a product and its users.
  • Command reference guide - Lists all commands for a release or product and provides instructions on how to use those commands.
  • Configuration guide - Provides instruction for how to use a software product to accomplish specific tasks.
  • System message guide - Provides information as to what specific user visible messages mean.
  • MIB specification guide - Provides information about the Management Information Base (MIBs) objects that can be managed on a device.
  • System overview - Provides a high-level view of a system comprising numerous software systems.
  • Technology references - Provide specific information about specific technologies (e.g., Ethernet over MPLS or Metro Aggregation).
  • User guide - Provides information on how to use a product.

There you have it, the two main types of technical writing.

0
Aside

What are the Technical Copywriting Basics?

Technical copywriting basics are the core principals of writing to sell technology. Here are some that you might find useful.

Study the Product

The first  is to study the product or service that you are going to sell so that you know each feature. Learn everything you can about it. Look at as much material (i.e., other sales efforts, specifications, customer complaints, testimonials, competing products, targeted customers) as you can. See what questions come up in your mind. Take copious notes. Soak yourself in this information, as you would soak in a steam bath.

Find All Possible Benefits

Now that you know all you can about the product, you must study take each feature and develop the benefits that each feature offers the customer. You must come up with as many benefits as you can.

Determine the Most Important Benefit

Now you take your list of benefits and determine what the single most important benefit is. How do you do this? First, you determine your specific target audience. You get this information typically from your client, from other sales material, and from marketing lists.

Then you make a considered judgment as to what benefit is the most important. This can be easy or difficult to do. However, it’s important. You cannot go on to the next step until you know what the most important benefit is for your target audience.

Present Your Sales Argument

Now that you know the most important benefit, you can develop your sales argument. Typically, you do this using a copywriting formula that you like. For example, you might use the AIDA (attention, interest, decision, action) formula for writing copy. There are a number of others. In all of them, you gain the attention of the reader with the most important benefit.

You use this benefit in your headline and in your lead paragraphs. You do this because you want your reader to continue reading.

Answer All Customer Questions

After you hook the reader with your best benefit, you can still lose her interest and let her slip away. One way to avoid this is by answering all your customer’s questions.

When someone reads sales material, questions spring to mind. If the reader scans your writing and doesn’t find answers to these questions, she is apt to stop reading. You want to avoid this.

You avoid this by anticipating all of the questions that she might logically anticipate and then weave them into your message. If the reader finds answer to these questions, then she is likely to continue reading.

Use Filters and Amplifiers

Siegfried Vogele developed this concept and writes about it in his book, Handbook of Direct Mail (he covers plenty of other copywriting basics in this book).

An amplifier is anything that gets a positive response from the reader. For example, a name spelled correctly or an attractive offer.

A filter is anything that gets a negative response from the reader. For example, a name spelled incorrectly or print that is too small to read easily.

The success of your copywriting effort depends on having many more amplifiers than filters.

Ask for a Response

Finally, ask for a response. What ever the purpose of your sales message is, ask for a response. And when you do that, make sure you give your reader a good reason to give you the response you want. Do that and you both benefit.

As technical copywriting basics (and any copywriting) go, I like these! What do you think?

0
Aside

Use Feature Article Writing to Sell Technology

Feature article writing can be an important tool in your technical copywriting toolbox. Let’s see how.

The most important point to remember about writing feature articles is that you can place an article about a product or service directly in front of the customer. Moreover, you do this using trade magazines that your company’s customers read and trust.

Feature Article Writing is About Trust

Trust is really what feature article writing is all about. We’ve all grown up reading newspapers and magazines. And, generally speaking, we believe what we read in them.

That’s why editorial advertising exists. You’ve no doubt seen editorial advertisements in newspapers or magazines. They are ads that look like they could be regular news articles except for one thing: the word “Advertisement” plainly printed above the copy.

No matter. People still read them and place a bit more credence in them just because of their format. Strange but true!

That’s why feature articles are so important. There is no word “Advertisement” in plain view. What people see is a factual and well-written article in a magazine that they trust for news and information about their industry.

So they are very receptive to what your article says about how your product or service works or how it can help with a problem. This is especially true if they have that same problem!

There is no need to exaggerate about how your product or service solved a problem that was previously unsolvable (unless it’s true!). The simple fact that there is an article about your product/service in a trusted publication provides tremendous credibility. That’s the power of feature article writing.

How to Get a Feature Article Published

Follow these basic steps to success with feature article writing:

First, determine your subject. It must be of interest to your customers. What problem can your article help them solve? Is there a customer who your product/service has helped and whose story you can tell?

Determine what magazine you want your article published in. If you are not sure, there are a number of directories on the web that list trade magazines. You can easily search by industry.

If you are familiar with the magazine, you have a good idea of what kind of articles they publish. If you aren’t familiar, locate several issues and carefully examine their content to see:

  • What are the topics that are typically covered?
  • What types of questions do the articles answer?
  • What is the typical article length?
  • Are there many pictures?
  • Who are the authorities that the author quotes to answer the questions that the article raises?
  • Who are the authors, business people, or freelance writers?
  • Who advertises?

A thorough examination will tell you if the magazine is a good fit for what you are considering.

When you find a magazine that you are interested in, look at their web site for writer’s guidelines. These guidelines will often provide specific do’s and don’ts for getting published in the magazine. If you cannot easily find the guidelines, email the managing editor and ask for them.

The Query Letter

The next step is the query letter where you propose your story idea. This is typically somewhat formal and no more than one page in length. This is where you show that your idea offers value to the magazine’s readers. You will do this with a lead paragraph in your query that could be the lead for your article.

Then you will describe what topics you will cover, suggest a possible title, and talk about who you will be interviewing for source material and for quotes in the article. You will also mention your plans for pictures or illustrations. In addition, you will introduce yourself and say why you are qualified to write this article.

Nowadays, it is possible to query by email. I prefer that way because it is cheaper and faster. Most magazines will let you know if they accept email queries. If they do, remember to maintain the same professional writing approach you would take if you actually sent a letter through the mail.

Being a technical writer or a marketing person doesn’t gain any extra points with editors. You still have to produce a well-written query and then deliver a professionally written article. Just like you, trade magazines are in business to serve their customers.

You may find that you enjoy feature article writing. In that event, not only will your company benefit, but you will too as your broaden your writing horizons.

0
Aside

Product Specifications | Just How Important Are They?

Product specifications provide the information that your customers need in order to decide whether to buy your product.

Depending on your industry, there are standard product specifications that customers expect when they “spec” out a product.

For hardware, these can include physical characteristics like size, weight, packaging, operating temperatures, operating altitude, acoustical noise, maintenance schedules, connection interfaces, disposal requirements, and airflow.

For software, customers are interested in software environments, compatibility with other software products, performance, features, and licensing to name just a few.

The more complete your product specifications are the better off you will be. That’s because, unless you have a long-term relationship with a customer, you don’t know what specifically is important to your potential customer.

You don’t want your customer scanning your spec and then putting it aside because something is missing. You want your customer to have all the information necessary to make an informed buying decision. In fact, your want your customer to use your specs as gold standard to measure other companies’ specifications.

Your product may be exactly what the customer needs but you risk losing the sale if your product specifications are lacking information. Why is that? It’s because you don’t know what feature is most important to your customer. If your specifications are saturated with technical information, you’re more likely to provide the answer to any question.

And they are of great value to your marketing team as well. How? Well, your product’s specifications can serve as the backbone for all your other marketing materials. You can look at each of the specifications as a feature of your product and then derive as many benefits as you can from each each feature.

When you have your completed list of benefits, determine what benefits are most important to your customers and get to work creating your marketing collateral.

0
Aside

Telecommuting for Tech Writers

Telecommuting for technical writers is an idea whose time has come. When you combine advances in Internet bandwidth with the increasing costs for both commuting and maintaining office facilities, it’s an idea that makes sense for both employers and employees.

I’ll start off by saying that for close to three years I telecommuted full-time as a technical writer for Cisco Systems. Cisco, of course, as a networking leader had telecommuting all figured out from the technical side. I never had any trouble getting into the secure VPN although on occasion I did have short-lived problems with my local cable company.

I was located in Herndon, VA, my manager was located in San Jose, CA, and the other writers and engineers I worked on a daily basis with were located in California, Nevada, Massachusetts, China, and India.

From a technical writing viewpoint, working from my home office was little different than working in my cubicle. The big difference was that there was more time for work.

Telecommuting saved time and money. Gasoline prices and the local commuter traffic were no longer an issue. Either was office politics; in fact, I became almost totally oblivious to the latest tech writer rumors.

I could get up early and start working almost immediately. This was especially helpful when dealing with fellow writers in India who were often not available during normal working hours.

I could call into meetings as necessary. I was also available for contact via AIM whenever someone needed to contact me.

Telecommuting did not affect the documentation cycle. It went on the same; I wasn’t really necessary as a physical presence. While there were some people I knew from actual physical meetings, most were simply usernames on emails or AIM. This was pretty much par for the course at Cisco because the people you worked with were often on other continents.

In fact, after this experience I wonder why telecommuting for technical writers is not more common for technical writers. Remote technical writing seems an ideal match. With today’s technologies, you can easily do from your home office anything you do at the workplace.

The only reason that comes to mind is that perhaps management has not yet figured out how to deal with the offsite technical writer. But as the advantages become increasingly obvious, you can expect to see increasing numbers of technical writers telecommuting.

For additional insights, see:

 

0

Serving Washington, DC and Northern VA