Technical Writing

Dallas-Fort-Worth (DFW) Texas based Brandfocal Consulting provides Branding, Search Engine Optimization (SEO), Content Management and Technical Writing services.


Technical writers document complex systems and processes into clear and effective manuals that serve tech-savvy developers, non-savvy end users, and everyone in between.

Technical Writing Services provided:

  • User documentation
  • Installation & maintenance manuals
  • Instructional guides
  • Risk and crisis management procedures
  • Factory acceptance procedures
  • Data analysis
  • Marketing research & promotion materials

Definitions

Technical writing is the process of researching and writing about specialized topics in a way that is clear to the intended audience.

Technical writers work closely with your subject matter experts (SMEs) to learn the details of your products, policies, and procedures. They take the time to understand you and your audience to eliminate the hassles caused by communication gaps.

Technical writing is meant to convey technical knowledge and its application in specific situations to a very specific audience. In most cases, that technical knowledge is about operation of a specific piece of computer software or hardware.

Today, technical writing encompasses all documentation of complex technical processes. It can include reports, executive summary statements, and briefs. Any time technical information is conveyed in writing at work, it is, by definition, technical writing.

The format is no longer bound to lengthy user manuals. Technical information must be distilled and presented unambiguously. This can come in the form of technical reports, emails, policy, briefs, and press releases.

Purpose

More often than not, documentation is treated as a lower priority task by many companies, especially those organizations that lack their own dedicated documentation or technical writing departments. While it’s understandable that documentation is not the primary expertise of technical companies, it is critically important that documentation is clear, concise, accurate and up to date. Studies have shown that poor documentation can lead to employee safety risks, increased liability, lost revenue, penalties, and even damaged reputations.

If your company does not have a dedicated documentation department, it pays to go with a professional and seasoned technical writing firm like Brandfocal Consulting. Our expertise allows you the time to focus on your core competencies while we produce the supporting documentation that your company will be proud to put their name on.

Types of documentation

Technical writers produce many different types of documents. The most visible documents are product manuals or books that accompany products to customers and instruct them on product usage. Online help consisting of a series of short instructional blurbs incorporated into the product itself is also common. Some technical writers never write any product documentation meant for external eyes but rather write product specification documents for internal use within the manufacturing company. Product specification documents are used to formally define what a product will do, its external interfaces (for instance, the type of menus and forms in the case of a graphical software application), and its internal interfaces (the available modes of communication from one part of the product to another; the functions front-end developers can use to access the underlying database in an application, for instance).

The importance of audience

The audience is a key element that many people fail to consider. When your job is to convey knowledge to someone, you need to understand what that person already knows and develop a sense of the teaching methods likely to work for that person. If you’re writing instructions for a customer service representative don’t assume they understand database theory or any of the associated terminology. It sounds obvious, but the failure to properly analyze the intended audience is the single largest pitfall facing technical writers.

Read more: The importance of audience

The importance of word choice and consistent writing

A good technical writer not only understands his intended audience, he understands the importance of clear and concise writing. Although most writers dream of beautiful prose that can move readers to another plane of existence, technical writing is all about removing any possible ambiguities so the reader understands precisely what to do. Short descriptive active sentences are generally better than long flowery lines filled with metaphor. Word choice is paramount to a technical writer. If there is any possible way an instruction can be misread or misconstrued someone will do so. When possible consequences of wrong actions are data corruption and data loss it becomes very important that users understand what you are telling them to do.

Consistency is also important. If you lead your users to expect all functions to appear in boldface followed by a set of parentheses, then make sure all functions appear that way. Otherwise, your readers may not realize that they’re all functions and could get confused. Similarly, keep a similar style and vocabulary throughout each document. If you’re writing an introduction filled with very general and basic conceptual material make sure you avoid as much technical terminology as possible and that you always define all terminology you do use. If several writers are collaborating on the same document make sure that individual voice doesn’t shine through. When the document is finished you should not be able to tell where one person stopped and another picked up. You shouldn’t even be able to tell that more than one person worked on the document.

Read more: The Importance of Word Choice and Consistent Writing

The importance of organization

Technical writers tend to pay more attention to organization and the order material gets presented than most other writers. In many cases, other writers have some leeway in presentation. More often than not the material can be organized in several different ways and still retain its effectiveness. This is not often true for technical writing. Since much of the time you’re either providing instructions – by their very nature a series of ordered steps – or providing background information that builds on prior material and tasks already completed organization is extremely important. If you fail to give users an essential step of any procedure they will not successfully complete that procedure. If you fail to discuss a basic topic before moving on to a related advanced topic they most likely will get confused.

It’s your job to analyze everything the user needs to do to successfully use a product and determine the order they need to do those items. Then you need to determine what the user is likely to already know and make sure that you provide every other scrap of needed information. In addition, you must analyze how someone who doesn’t understand the product as well as you do would think about the product and provide logical entry points to the necessary material given those expectations. It doesn’t help to provide every scrap of information your users need if they can’t find that information within your document.

The importance of indexing

Indexing is an important but often overlooked step in this process. Most users are going to either turn directly to your table of contents or turn directly to your index and start looking for the material they think they need. You need to make sure that information can be found from either method even if the user doesn’t yet know precise terminology or an exact word to look up. Cross-indexing is an art, one that eludes many otherwise very competent technical writers. Indexing is a skill that needs to be developed and practiced regularly.

Read more: Indexing Your Documents

The importance of editing and review

You might think the process of technical writing is complete once you put the last word on the page, but it isn’t. Every document needs to be reviewed and edited. In some cases, you will be fortunate enough to have an actual editor in place to edit your document, but most technical writers must rely on another technical writer or even do it themselves. In addition to the normal editing tasks of checking grammar, general word usage, and spelling, technical editing includes several other elements including checks for consistent word usage, checks that a consistent audience is maintained, and checks that the organizational choices make sense.

Reviewing often occurs at the same time as the editing process but it serves a very different purpose. While editing ensures a clean grammatically correct document with consistent style, it doesn’t test the accuracy of the content in any way. Reviewing does. If possible, you should have at least one of the developers who wrote the product participate in a review as well as at least one person who fits the target audience profile. If the person within the target audience doesn’t understand everything you wrote then even if it’s accurate you haven’t successfully met your mandate and need to re-write the document accordingly. If the developer finds inaccuracies or points out areas where the product was changed then similarly you need to fix those before declaring the document finished.

Read more: Editing and Reviews

See also: