What is Technical Writing?

Technical Writing, sometimes called business writing, is writing for a specific purpose and with a
specific goal. Usually its goal is to inform/instruct or persuade/argue. Technical writing can really be
considered transactional writing because there are two people or groups involved in the
communication. One party has a clear goal to inform or persuade the other party. This is real-world
writing in every sense. You may not be aware of how much it already impacts your world through
textbooks, instructions, web sites, and communications from many businesses and service
organizations. There are professional technical communicators but only large organizations have
them and even then they are not there to
do your daily work for you and that is why it is so helpful for many to take at least an introductory
technical writing class.

Why is Technical Writing Important?

Why is technical communication important and what will you use it for? Actually, technical writing
will be used by most college graduates as a regular part of their work. It is much more likely that you
will use technical writing than either academic or creative writing unless you specifically enter those
fields. A few examples of why you will likely need these skills include: getting a job – preparing a
resume or curriculum vitae, cover letter, application, and portfolio; doing your job – preparing
memos, letters, reports, instructions, case reports, reviews, assignments, descriptions, etc.; and
keeping your job – communicating with management, co-workers, peers, patients/students/public.

What separates technical communication from other forms of writing?

Technical communication has a specific audience and is purposeful, usually intended to solve a
problem for that audience. One area that really sets technical communication apart is that it is quite
often collaborative. Technical communication is also focused on readability issues, not only the use of
clear writing, but also page design and graphics. The excellence of technical writing is judged by
clarity, accuracy, comprehensiveness, accessibility, conciseness, professional appearance, and
correctness.
There are seven principles to guide technical writing: remember your purpose (to inform or
persuade), remember your audience (their concerns, background, attitude toward your purpose),
make your content specific to its purpose and audience, write clearly and precisely (active voice,
appropriate language to audience), make good use of visuals (good page design and graphics), and be
ethical (truthful, full disclosure, no plagiarizing).

Technical communication serves both explicit, or clear, and implicit, or implied, purposes. Explicit
purposes include to provide information, to provide instructions, to persuade the reader to act upon
the information, or to enact or prohibit something. Implicit purposes include establishing a
relationship, creating trust, establishing credibility, and documenting actions. Most technical
communications are based on a problem statement which gives your document a clearly stated
objective for your benefit as well as your reader’s. The problem statement defines the problem, by
doing more than simply stating your topic, it goes on to explain what about that topic is at issue.
For example, if your topic is career guidance then your problem could be the fact that many adults
need help identifying a career that suits their strengths and abilities and the solution that your
document will present is to create a comprehensive clearing house that helps people identify career
paths through military, vocational training, and higher education.
The Principles of Technical Writing

Well-written and accurate documentation plays a major role in any company’s customer support
strategy because it helps to reduce support costs. Technical writing plays a big part in the support
equation.

Technical writing is much more than just technical jargon, and structured, concise instructions. As
the intended audience for the technical writing could be for both technical and not-technical people
it must to convey its message so that both sets of people understand it.

The main purpose of a technical writer when approaching a new technical writing project is to
ensure that they maintain focused on what they are writing about. The information they are
producing has to be organized and structured within the laid down style that is appropriate for the
intended audience. By sticking to the basic principles of technical writing the technical writer is
ensuring that the documentation is clearly understood by the reader.

The following is the six basic principles of technical writing that a technical writer has to take in to
consideration.

Content

There are five basic questions a technical writer has to ask themselves when starting a new project –
who, why, what, how and when. Answering these questions will allow the technical writer to be able
to develop the content for any type of technical documentation. For example, let’s say the technical
writer has to create a user guide for a new video recorder. Before creating the user guide, they will
have to plan the content of the user guide by applying following key questions to the situation:

Who will read the user guide?

Why do need to create the user guide?
What is this user guide going to offer its intended audience?
How is the user guide going to be delivered?
When does the user guide have to be ready (publishing date)?

The audience and purpose of the documentation

Before beginning any new writing project, the technical writer has to analyze the intended audience
and identify the purpose for the document. The technical writer will need to ask the following
questions about the audience:

Who will read the documentation?

What are their biases?
What responsibilities does the technical writer have when communicating the information to the
audience?

With regard to the purpose of the documentation, technical writer will need to know what the
documentation will accomplish and also what should it do.

Styleguide

Technical writers will more than likely use a company styleguide (if there is one) to ensure that their
documentation has a structured and organized pattern so that it gives consistency to their writing. A
styleguide will provide the document with continuity so that the audience can comprehend the
information. For example, technical writers need to organise their ideas in a specific chronological
format because without a specific layout and structure to the documentation it will be very
confusing for the reader to understand.

Writing Style

Technical writers will need to change their writing style depending on the audience and situation
they are writing about. If they are writing technical documentation then it needs to be formal and
devoid of any emotion as you get with creative writing. Whereas, if say they were an email to one of
the senior managers involved in the project then their approach would more casual than formal.

Accessing the information

Accessibility applies to the ease at which the intended audience can gain access to the information
they need from the technical documentation. A technical document must at least contain a table of
contents, headers and footers, list of illustrations/tables, page numbers, etc.
Also a technical document must adhere to a specific heading and sub heading structure to break
down the information into relevant areas that the reader can access easily.

Grammar

A technical writer must adhere to all the rules of conventional grammar. Also it is the technical
writer’s responsibility to proofread and edit their documentation to detect and correct any errors in
the writing, graphics, typography and layout.

In summarising, a technical writer must ensure that they incorporate the above mentioned
principles into their everyday writing style. This will go a long to make them not only a better writer
but their technical documentation will be appreciated by both their peers and readers alike.
What are the Principles of Technical Writing?

Well-written and accurate documentation is the part of customer support strategy, and reduces
support costs. Technical writing is much more than technical terminology, and curt instructions. Our
audience is made up of humans , and not just technical personnel. Technical writing requires that
the writer present a main point or thesis, maintain focus, organize and develop ideas, and use the
appropriate style for the audience. The following are the basic principles of technical writing.

• Content

Five basic questions – who, why, what, how and when – are applied in various situations to develop
the content for any kind of a document. For instance, imagine a situation where you have to create a
report based on your balance sheet. Before creating a report, you can plan the content of your
report by applying following key questions to the situation:

o Who would like to read the report?

o Why do you want to/or need to present a report?
o What this report is going to present to the audience?
o How is the report going to be presented?
o When is the report going to be presented?

• The writing situation: Audience and Purpose

Before beginning any writing task, the writer analyzes audience and identifies the purpose for the
document. The writer asks following questions about the audience:

o Who will read the document?

o What are their biases?
o What are technical writer’s ethical responsibilities when communicating this to audience?

With regard to purpose, technical writers ask: what should this document accomplish? What should
it do? Should it:
o Inform
o Request
o Instruct
o Suggest
o Order
o Report
o Reply
o Analyse/ critique
o Compare

• Organization

Writers use an organizational pattern so that it gives consistency to writing. Organizational pattern
provide the document with continuity so that audience can comprehend the ideas. For example,
writers can organize their ideas chronologically, spatially and categorically.

• Style

Writers change their style depending on the audience. A person would not write an e-mail to a close
friend in the same style as a formal memorandum to a manager. Writers adopt either formal or
informal styles, depending on the writing situation.

• Accessibility and Specificity

Accessibility refers to the ease at which the audience can gain the information they need from a
document. Table of contents, headers, footers, page numbers, headings and sub headings help make
the document more accessible for the intended audiences.

• Conventional Grammar and Mechanics

Writers adhere to the rules of conventional grammar and mechanics. Technical writers essentially
proofread and edit the document for detecting and correcting errors in graphics, typography and
layout.
Technical Writing Principles

If you take a technical writing workshop, the materials will address numerous areas; some are very
specific while others are more general in nature. A good starting point is to look at six principles of
technical writing. Reviewing these basics can provide a great platform from which we can launch
forays into specific areas of interest and documentation.

Use Good Grammar

Write Concisely
Use the Active Voice
Use Positive Statements
Avoid Long Sentences
Punctuate Correctly

Principle One: Use Good Grammar

Your readers expect technical documents to be written in standard English. Certain grammatical
errors can actually cause your reader to misinterpret the information. However, because technical
documents must be precise and accurate, readers expect documents to be professional, polished,
and flawless.
One grammatical rule to adhere to is subject-verb agreement. Note the choice of verbs below:

One employee is absent.

Two employees are absent.

This subject-verb agreement is easy to make because in each sentence, the subject is
obvious: employee in the first sentence agrees with is and employees in the second sentence agrees
with are . The real challenge is when the subject is not as obvious. In the following sentences, which
verb would you select?

Either of the levers is clearly marked.

Either of the levers are clearly marked?

You must decide if the subject is either or levers . If you selected either as the subject and is as the
verb, you made the correct choice. A list of indefinite pronouns that are always singular is listed
below:
Each, either, everybody, everyone, neither, one, anyone, anybody, someone, somebody, no one,
nobody

The following indefinite pronouns are always plural:

Both, few, many, several

Just to keep your life interesting, the following pronouns can be either singular or plural.
All, more, most, none, some

You may wonder how some pronouns can be both singular and plural. Review the following
examples:

Some of the information is inaccurate.

Some of the figures are inaccurate.

If grammar is a weak area for you, purchase and use a good reference book.
Principle Two: Writing Concisely

In technical writing, clarity and brevity is your goal. Why take 32 words to express what could be
stated in 14 or 15? The dictates of effective technical writing suggest that the average length for a
sentence is 15-20 words. How do you achieve clarity and conciseness?

One of the best ways is to look for multiword phrases that can be replaced by one or two words. Try
replacing the multiword phrases below with a word or two.

A large number of ________________

Prior to that time ________________
In the process of tabulating ________________
As shown in table 3 ________________
Exhibits the ability ________________

Similarly, when you streamline sentences, your readers don't have to wade through extra verbiage.
How would you streamline the sentence below?

"To obtain maximum performance from your computer, you should endeavor to follow the
maintenance program furnished in the manual accompanying your computer."

Experts have found that there are two ways we lose our readers: using words with which they are
unfamiliar and overly long sentences. By replacing wordy phrases with shorter ones and by pruning
the deadwood from sentences, you are doing your readers a favor.

NOTE: Answers: many, before, when tabulating, table 3 shows, can

To enhance your computer's performance, follow the manual's maintenance program.

Principle Three: Using the Active Voice

Imperative sentences, or command sentences, are written in the active voice. The active voice is
more natural to people when they speak, but technical writers often turn to the passive voice when
writing technical documents. One of the main reasons you should use the active voice rather than
the passive in technical writing is the active voice more closely resembles the way people remember
and process information.

Compare the following sentences:

Staff hours are calculated by the manager on the actual work load.
The manager calculates staff hours on the actual work load.

In the active voice sentence, the subject acts. In the passive voice sentence, something is done to the
subject.

Another reason to avoid the passive voice sentence is you run the risk of omitting the doer of the
action. Note the absence of the "doer" in the following sentence:

Documented practical examinations will be given for backhoes of the same type with different
operating characteristics.

Your reader will probably wonder who will give the practical examinations. If the technical writer
had used the active voice, the "doer" would be clear.
Principle Four: Using Positive Statements
Technical writers should word instructions as positive statements. Whenever possible, phrase
commands in a positive manner. Compare the following:

Negative: Do not close the valve.

Positive: Leave the valve open.

Telling your readers what NOT to do is a negative statement. It is also abstract rather than concrete.
Your readers have to take time to think about what is true (positive) so they can determine what is
NOT true (negative).

One exception to this rule is when a negative statement is clearer than a positive one. Keep in mind
studies show it is almost 50% harder for your readers to understand the meaning when you use
negatives.

Principle Five: Avoiding Long Sentences

Short sentences are easier to understand than long sentences. For this reason, it is best to write your
technical documents in short sentences. If you are asking your readers to perform several actions,
begin the step with an active verb. This highlights the action itself. Compare the following sentences:
Example of a sentence with multiple steps within the sentence:

For Forte applications, create an empty workspace, populate it with application source code, and
compile the workspace.

Example of a sentence with multiple steps set apart:

For Forte applications, perform the following steps:

Create an empty workspace.
Populate it with application source code.
Compile the workspace.

Another tip when separating steps into distinct bullet points is to make sure that the action verbs in
each bulleted item are in the same tense. For example, if the first step was worded, "Creating an
empty workspace ," then the next bullet would be, "Populating it with application source code ," and
the third bullet point would be, "Compiling the workspace ."

Principle Six: Using Standard Punctuation

Your readers expect standard punctuation when they read your documents. Complicated or
"creative" punctuation will confuse them. One suggestion is to select syntax that minimizes the need
for punctuation. You may wish to divide compound or complex sentences into shorter sentences to
avoid excessive or confusing punctuation.

One example of this is deciding where to place your commas, periods, colons, and semicolons when
using quotation marks. Commas and periods always go inside the closing quotation mark.

Examples:
We are "struggling young artists," but we hope to become successful.
Most corporations adopt the belief, "the customer is always right."
On the other hand, semicolons and colons are always placed outside the quotation marks.

Examples:
These actors can deliver "box office hits": Tom Cruise, Tom Hanks, Johnny Depp.
Look in the manual under "text messaging"; the directions are very clear.

Many technical writing workshops focus on advanced topics, expecting participants to already be
familiar with the basic tenets of good technical writing. While these six principles are a good starting
point, you may be surprised to see how often they are ignored within your own organization—and
your industry. Challenge yourself to read and analyze other technical documents and ask yourself:
What makes some documents a struggle to read while others are easy to comprehend? As you
incorporate these and other sound writing techniques, your readers will benefit.
10 technical writing principles to live by
by Tom Johnson on Jun 20, 2014
categories: technical-writing

As I started my new job, I've been thinking about the most important technical writing principles I've
learned in the past. The following are 10 principles to live by when doing technical writing.

1. Always test out the instructions yourself.

Unless you can walk through the instructions and perform the tasks yourself, it will be difficult to
evaluate the help material. Testing the instructions seems like a given, and with GUI documentation,
it usually is. But in reality, it can be complicated to do this. You may need to set up a special server
environment or scenario. The information may involve testing certain API calls and methods that
require more advanced knowledge, and which may only be accessible under certain conditions.

Other scenarios may pose greater restrictions, such as million dollar hardware projects you can't
even touch.

Regardless, it's pretty easy to tell when a technical writer has written instructions solely based on
information someone else has shared rather than information the tech writer gathered from first-
hand experience. Always strive to walk through the instructions and try them out yourself.

2. Work with QA to get test cases for what you're documenting.

QA (quality assurance) people are your best friends. They know the system better than anyone else.
They've set up test environments to ensure the functionality, and they often have a set of test cases
(features to try) for each release. If you're documenting an API, the QA engineers might already have
the calls to test in ready-to-go formats. Piggybacking on QA efforts can make writing documentation
a lot easier.

However, QA often doesn't have the higher level business information about the various scenarios
the features will be used in. They're mainly testing whether the features work or not. You need to
get the higher level picture from product managers. Still, working closely with QA can make your life
much easier.

3. Developers almost always overestimate the technical abilities of their audience.

Developers often create products with a certain audience level in mind, and usually they assume the
audience is a lot more familiar with the company's technology than they actually are. In reality, users
often need more hand-holding and simple instructions than developers think. Users may resort to
copying snippets of code, they may not be as familiar with the programming languages, or they may
not want to devote the time to studying out your product.

Whenever you hear developers say things like, “If users can't figure this out, they shouldn't be using
our product,” bells should go off in your head. Almost always assume the user is several notches less
savvy than your developers assume. It's better to err on the side of documentation that's too simple
or obvious rather than documentation that is too cryptic and abbreviated.
4. You can't evaluate documentation without including user feedback.

You need to get direct feedback from customers to really know the value of the documentation.
Whether users understand the documentation or not, whether it meets their needs, and so forth, is
really a guessing game unless you get more tangible feedback from the intended people who
actually use the help products.

Because of the need to incorporate user input, you should have some interaction (even if indirect
through a support center or forum) to be able to evaluate the help material. Just remember that you
can't evaluate the help from your experience alone. Even if you've tested all the instructions and
found that they work, you may be missing large portions of needed information, or you may have
misjudged the deployment platforms and scenarios, and so on.

5. Always plan for collaborative authoring solutions.

Even if you don't need collaborative authoring now, you'll most likely need it at some future point.
The idea that a single person working from a single point of view can create documentation that
applies to everyone in every business situation, on every platform and device, in every location and
language and role, is highly impractical.

You may be the lone author that your company pushes documentation through, but at some future
point, the company may add more authors who contribute to the same projects, or they may lay off
the writers and rely on other non-writer employees to contribute. Either way, in this day and age, a
tech writing method that doesn't allow for collaboration is potentially shortsighted in the long run.

6. Focus less on the publishing platform and more on the content

It's easy to get sucked into publishing details for your help tools, but that should never be your
primary focus (unless you're the designated tools expert for a large team of writers who are focusing
on content development). In most situations, the tool isn't the problem — it's the content. Help lives
or dies by the quality of the content, not by look and design of the help. I've seen so many tech
writing teams focus on improving help by focusing on the tools. Really I think tools contribute only
marginally to the quality of the help experience.

Of course, there's a certain standard for tools. Your tools have to provide your help output with
some basic navigation controls, search, table of contents, and other features. But where possible,
choose tools that don't require you to devote enormous amounts of time to configure and set up.
Choose a simple method and devote that time to the content instead.

7. Balance text with visuals.

If you want to make help look sexy, add visuals. Whether the visuals are diagrams, workflows,
illustrations, or even just annotated screenshots, visuals add a lot to help material. They balance out
text, provide another format for comprehension, and connect to the visual learning modes of our
brains. Visuals are sometimes tedious to create, but the payoff is worth it.

Granted, if you're translating your material and all languages receive equal treatment, or if you're
focusing more on code samples than visuals, you may not have a lot of images in your content. But
you should still strive to communicate visually when possible. It's too easy to marginalize visual
communication and rely entirely on text.
8. Examples clarify complicated concepts more than almost anything else.

If you have something complicated, the best way to clarify it for your reader is usually through
examples. Every example you add usually gives your content more and more clarity.
If you add three examples to clarify a confusing concept, your audience will probably get it in a much
clearer way than if you add just one example. Granted, not everything merits an example, or even
more than one example, but just remember that examples are a tool in your tech writer tool belt to
communicate complex information in a way users will understand. More examples often means
more clarity.

9. Always keep learning.

With the rapid growth of technology, technical writers must always be learning. The learning process
should be a continued emphasis, one that technical writers regularly incorporate into their daily
study. The resources online make learning easy. You can get more than a dozen books on nearly
every technology or platform available, both written and video versions of the instructions.
Often tech writers who work in the same roles for more than several years may face a danger in
becoming too comfortable with their technology understanding. Working on a variety of projects,
with different features, platforms, languages, and audiences can help you stay fresh and current. The
technical writer who is mostly a writer and not very technical will not be nearly as marketable as one
who places a strong emphasis on tech. This is particularly true with developer documentation.

10. Your primary deliverable should be a web format.

Many of us have been operating in the book mindset for so long we sometimes are blind to all the
assumptions we bring to projects. If we target our primary deliverable as a web format, we can more
appropriately write for what is often the primary way users will interact with our content.

Writing for the web means writing pages that have complete information for users to achieve a goal
(what Mark Baker calls “Every page is page one”), leveraging interactivity (such as embedded tabs or
filters that allow users to click tabs for code samples in different programming languages),
optimizing for search features that retrieve relevant results (which might require metadata and
dynamic filtering), and more. Online formats provide the possibility of online tracking, on-the-fly
updates, and more. If we write for a printed, static medium (PDF) as our primary medium, we often
miss all the possibilities of the web.

https://afendirojan.files.wordpress.com/2010/04/principles-of-technical-writing.pdf