TECHNICAL WRITING

UNIT - 1

What is Technical Writing?

Technical writing is the art of conveying complex information in a clear, concise,

and accessible manner. It’s a specialized form of writing that focuses on making
complex ideas easy to understand for a specific audience. Whether it’s a manual,
a report, or a set of instructions, the goal of technical writing is to explain
technical information in a simple way that anyone can easily follow, whether
they are experts or beginners.

Difference Between Technical Writing and Other Forms of Writing

Technical Writing Other Forms of Writing

 Format
There are many different types
of general writing. For example, There is usually a
there are numerous ways to create predetermined structure to
a blog in order to keep the reader follow in technical writing. This
interested and entertained. guarantees that the information
given is concise and that end-
users can begin utilising the
product right away.
 Writing Style
In technical writing, the content is
always written in a third-person To make the non-technical text
format to make things easier for feel conversational and
the reader. It’s also super-formal, interesting, writers frequently
so there’s no room for different employ the first-person
interpretations of the content. nalrrative and informal tone.
 The Tone of the Content
The nature of technical writing is
always objective. There can’t be Non-technical content is
any disputes or confusion in the typically written in a subjective
directions. tone, using stories and personal
 experiences.
 Intended Purpose
The sole purpose of technical
content is to improve the user The objective of non-technical
experience. It only provides content pieces is mainly for
information, instruction, and entertainment or commercial
explanations about the topic, purposes.
application, or equipment in
question.
 Focus Area
Technical writing focuses solely
on the issues at hand. A user Other types of writing might
handbook, for example, focuses provide the content piece with a
solely on the product’s functions. lot more variety and creativity.
For example, an e-learning blog
might discuss how to better
conduct classes as well as the
estimated cost of beginning
your own e-learning academy.
 Vocabulary
The terminology used in technical
writing is extremely specialised The vocabulary employed In
and based on the type of product. non-technical writing is
Specialized terminology is typically suggestive in nature, in
utilised in the material to offer the order to elicit an action or
reader accurate instructions or emotion from the reader.
explanations.
 Audience
The audience in technical writing
is always specialised and The audience with the other
knowledgeable. They could also type of writing is far broader.
be business analysts or product There may be significant
managers who want information differences in their age groups,
on the programme or service in professions, and other factors.
order to maximise its In other words, the literature is
effectiveness. not intended for a certain group
of people.

QUALITIES AND QUALIFICATIONS OF A TECHNICAL WRITERS :

A technical writer is someone who writes technical documentation such as user
guides, software manuals, and online help for technical products. They provide
step-by-step instructions or tutorials on how to use a product or service. The main
skills needed to be a technical writer are summarized below.
Many technical writers have degrees in technical writing, professional writing or
English. Your coursework might include business writing, nonfiction writing and
editing. It’s helpful to take additional technological courses to prepare for a career
in technical writing. You can also earn a degree in engineering, computer science
or a related technical field, then take courses in communications and business
writing. Usually, a four-year degree is sufficient to get a technical writing job, but
some of these writers also have graduate degrees.

Qualities of a Good Technical Writer: Love of Technology

Love of technology and software, and the ability to upgrade one’s tech skills
regularly.
A good technical writer is someone who has a love of technology. They need to be
able to understand the technology that they are writing about, in order to be able to
explain it in a way that others can understand. They also need to be up-to-date on
the latest trends and developments in their field, so that they can write about them
in a way that is accurate and informative.

Qualities of a Good Technical Writer: Love of Writing

Love of writing and the ability to understand and formulate procedural steps.
A good technical writer is also someone who loves to write. They need to be able
to communicate effectively in writing, and be able to produce high-quality content
that is easy for readers to understand. They also need to be able to stay on top of
deadlines, and meet all the requirements of their project.

Qualities of a Good Technical Writer: Plain Writing

Ability to write plainly, simply, without the pride of authorship.
A good technical writer also understands the importance of plain writing. They
know that it is important to write in a way that is easy for readers to understand,
without using too much technical jargon. They also know how to use graphics and
other multimedia elements to help explain technical concepts in a clear and concise
way.

Problem Solving
Love of solving puzzles and finding solutions to problems. The courage not to run
away or get depressed when one is faced with a situation that requires calm
rethinking and innovating.
A good technical writer needs to have strong problem-solving ability. They need to
understand what problems might come up while they are writing, and how they can
solve them if they do. This will help them deliver the content on time, and avoid
any mistakes that could bring their project down.

Learning New Things

Courage and appetite to learn new things fast.
Every technical writer is well aware that “the more you learn, the better your
writing becomes.”
As technical writers, we constantly need to be learning and developing our skills.
Even technical writers who’ve been in the field for a long time probably aren’t
experts at everything they write about. There’s always something new to learn, and
as technical writers we should always be seeking out new information and ideas to
improve our technical writing skills.
Technical writers need technical knowledge, industry knowledge, and technical
writing knowledge:

1) Qualities of a Good Technical Writer: Technical Knowledge

Technical writers need to understand what they’re writing about. They must know
the background of their subject and how it works so that they can explain it clearly
to readers.

2) Qualities of a Good Technical Writer: Industry Knowledge

Technical writers must also be familiar with the industry their writing pertains to.
They need to know the terminology and what is generally accepted within that
industry.
3) Qualities of a Good Technical Writer: Technical Writing Skills
Technical writing is a specific genre with its own set of rules. A good technical
writer must be familiar with these rules and how to apply them to technical writing
situations.

Love of Order
Love of order, structure, and hierarchy. Allergy for ambiguity and disorder.
This includes organizational skills like the ability to organize and schedule work,
ability to use Excel for project record-keeping, accountability and transparency.
One of the qualities of a good technical writer is an appreciation for order. This
means keeping your work tidy and well-organized, both on paper and in your head.
When everything is in its place, it’s easier to find what you need and to make
changes when necessary. In addition, a neat and orderly document looks more
professional and always creates higher user satisfaction, which is the main goal of
technical communication.

Listening Skills
Ability to listen carefully, without thinking “what shall I say next as an answer?”
No-ego-listening.
Being a technical writer has its advantages. It can be exciting to jump into
something new every day, and technical writers are afforded the opportunity to
work in an environment where they constantly learn new things.
However, technical writing is more than just filling up technical manuals with
information; it’s about listening to clients’ requirements, understanding the
technicalities of the subject matter, and conveying that information to readers in a
manner that is easy to understand.
How you present technical content has an impact on how easily it can be
understood by technical users.
Computer skills are key when you’re in technical writing, but learning new ones is
no longer an issue for technical writers because technical support employees are
typically cross-trained in multiple areas.
What really sets technical writers apart is their ability to listen and understand
client’s needs, translating that into clear and concise instructions for
technical users.
A good technical writer has excellent listening skills to gather all the required
information from clients and other technical staff.

Team Player
Ability to get along well with others in a team environment.
Most of the time, even if you are an alone writer working remotely, you will need
to be able to work well within a team. As a technical writer, you will often be
communicating with engineers, product managers, project managers, and other
stakeholders to gather information and compile documents. You need to be able
to effectively communicate with these individuals in order to gather the necessary
information and produce high-quality documentation.

Appreciation of Others
Ability to appreciate with a glad heart what smart people around you are
accomplishing.
In order to be a good technical writer, it is important to appreciate the work of
others. When you understand the importance of everyone’s role in producing a
final product, it becomes easier to put forth your best effort. You learn not to take
things for granted and to be more willing to ask for help when needed. This also
leads to a better working environment and a team that is more cohesive.

Endless Curiosity
Endless curiosity about how the world works and how one can improve one’s
company and community.
In order to be a good technical writer, one must have endless curiosity. This means
that you must be inquisitive and always want to learn more. As a technical writer,
you are responsible for conveying complex technical information in a way that is
easy for others to understand. This requires being able to understand the
technology yourself and then finding the best way to explain it to others.
In order to do this, you must be able to ask the right questions and have a desire to
find the answers. You must also be willing to keep learning, even after you have
obtained a certain level of knowledge. Technology is always evolving, so you must
be prepared to continually update your understanding of it.

Insistence on Accuracy
An unconditional insistence on accuracy. Refusal to accept mediocrity.
In technical writing, the language is very important. Unless you were to use
symbols instead of words for technical manuals, technical writers must be 100
percent accurate in their technical writing.
A technical writer should have an excellent vocabulary and command
of grammar so that readers can understand technical information clearly from how
it is written. Such qualities also make technical documentation more readable and
concise. The technical writer’s job is to make sure that the reader understands the
information, so if there are any inconsistencies in the language, it can lead to
confusion on the part of the reader.
In addition, the content of the documents, i.e., the procedural steps, figure captions,
table content, etc. must be accurate as well. No matter how well a document is
written, if the information it shares is not accurate, then it’s worth nothing.

UNIT – 5
Stage 1 of the technical writing process: Prewriting
Prewriting refers to everything you do before writing an actual draft. Prewriting is the
stage in the technical writing process in which you define the direction and strategy for
the content you're about to write.

Do these prewriting tasks well, and writing the draft will be a breeze.

1. Define your audience

To create effective content (i.e, content that will be useful to your audience), you need
to understand who they are. When you understand your audience, you'd be able to write
content that resonates with, impacts, and offers them a better reading experience.

To define your audience, ask yourself: Who

am I writing this piece of
content for? Are they beginner developers, mid-level
developers, product managers, designers, etc?
Your intended audience determines the tone you should lean on while writing, the level
of background information you need to provide, the frequency with which you define
terminology, what you should cover and shouldn't, and the overall direction of the
content.

2. Define the goal of your technical content

Every piece of content you write should have a goal; otherwise, you'll write something
that doesn't deliver any value because your points will be all over the place. Just like
defining your audience, defining the goal of every piece of content helps provide you
with more direction and focus.

The goal of every piece of content can be thought of in two parts: the producer's goal
and the readers' goal.

The producer's goal

A producer is someone or a group of persons who wants to write a piece of content. In
this case, the producer is you (an individual technical writer writing for yourself, or the
company paying for you).

Defining the producer's goal helps you understand why you or your company has
decided to write a particular piece of content. Without specifying this goal, you're less
likely to care about what you're writing. And, when you don't care about what you're
writing, you're less likely to deliver value.

To define your producer goals, ask yourself these questions:

"As a person, why do I want to write this piece of

content?"
 "As a company, why should we produce this piece of
content?"
The readers' goal
The readers' goal is why your audience should care about your content or even read it.
When users search for content, their goal is usually to either get a solution to a pain
point or find answers to a pressing question.
To understand your readers' goal, ask yourself:

 "What are the pain points of my target audience regarding

this particular topic?",
 "Regarding this particular topic, what are the pressing
questions that my audience are looking for answers to?"
As much as your goals are important, that of your audience is more important. It is only
when you create value for your audience that they will convert (i.e help you achieve
your own goal). So, you need to marry your goals to that of your audience, to achieve
better results.

3. Write an outline
An outline is like a map that guides you to a destination — without which you'll end up
missing your way.

An outline can be described as the barebones structure of your content. It allows you to
narrow down your ideas to the main points that you need to cover, ensuring that you
deliver on the goal of that specific piece of content without deviating.

An outline typically contains:

 A title
 A thesis (the primary point of the article), and
 Headings and sub-headings representing the points you'll
need to cover to deliver on your content goal.
4. Do your research
Research is a vital step in writing. So crucial that I'd like to say that a successful piece of
writing depends on 60% research, 10% writing, 10% editing, and 20% distribution.

Research is a continuous process when writing. From the moment you decide what to
write on, to defining your target audience, to drawing up an outline, you must conduct
research to gain perspective. The level of research you do will reflect on how confident
you'll feel about writing that particular piece of content.

So after you've drawn up an outline, do some research and read up on existing similar
or related content to gain more understanding and authority over the topic. If you need
to build out a demo app or write some code, this would also be a good time to do that.

Stage 2 of the technical writing process: Time to

write
After defining the basic structure and direction and reading up on helpful information, it's
time to start writing.
1. Write the first draft.
The goal of the first draft is to help you get all of the ideas in your head onto paper
(within the constraints of your outline and target audience, of course). Write down all of
the ideas that come to you in relation to your outline. It doesn't have to look good or
even be moderately ready for publishing. Write, then fix later.

While writing out this draft, you may likely get stuck on some areas. That's perfectly
normal. This might indicate that you need to stop and go do more research or consult
someone knowledgeable about the topic. Alternatively, mark the section that needs to
be worked on as Todo and continue writing the sections that you flow freely to you.

2. Rewrite the first draft

The goal of this rewrite is to organize all of the ideas that were jumbled together in your
first draft into a coherent and presentable format.

In this phase, you should arrange paragraphs and sentences one after the other to
achieve flow and remove any awkward phrases or duplicate information. It would help if
you also wrote a proper intro and outro.

Your intro should answer the question: "Will this help me?, Should I be reading this?". It
needs to contain the goal of the content (what the user will learn from the content), and
any prerequisites knowledge they need to have.

In contrast, your outro should include the next steps for the reader (what should they do
next after reading your article). This can include anything from relevant links to
additional resources.

Asides that, here's a list of other things to do in the rewrite phase:

 Rewrite every paragraph and section with the key ideas

positioned first, to promote readability.
 Remove anything that doesn't support your main point or
will distract from key points.
 Verify that there are no gaps in your writing and that
you've provided all the information the reader needs to
arrive at the goal set out at the beginning.
Typically I'd say put some distance between your first draft and every rewrite. If you can
afford the luxury of time, the next day is best. This allows you to have a fresh
perspective and brain.
3. Fine-tune and polish
Now, this is the stage where you read through your more polished writing sentence by
sentence and try to clean it up even more. Unlike the rewriting, which is more
concerned with high-level coherence, this phase is about minute tweaks.

Here's a checklist of some things to do at this stage:

 Remove awkward phrases or ambiguous words that may

make it hard for the reader to understand the content.
 Make sure all links work
 Create smooth transitions between paragraphs and
sentences.
 Run content through a grammar checker like Grammarly
 Run a plagiarism check using a tool like Grammarly
or Unicheck.
 Break down longer sentences of more than 25 words into
two.
 Break paragraphs into a maximum span of 6 lines.
 Clean out your subheaders. Make them as brief and as
clear as possible.

Stage 3 of the technical writing process: After

writing…
Now that you're done with writing, it's time to ask for feedback and get it ready for
publishing.

1. Ask for feedback

You can either stop at the fine-tuning stage and move on to the publishing phase, or ask
for feedback from an extra pair of eyes (like a friend) if you're writing for yourself.

If you're working in a professional setting, you'd usually send this to your clients or
superiors for feedback and then try to incorporate their suggestions.
2. Publish and share
After you've incorporated feedback, it's now time to publish. You'd typically transfer the
content from your drafting location (google doc, dropbox, e.t.c) to the publishing medium
(code editor, markdown files, CMS). Then share the excellent content you've written to
social media so other people can see it.

What's the essence of writing if no one ever sees it?

Take care not to get stuck on the editing and polishing loop. The thing about technical
writing is that there will always be room for more tweaking, some more editing, or
something you can do to make it better. But do that, and you'll never finish.

As Leonardo da Vinci said: "Art is never finished but abandoned". Set a

deadline, stick to it, and consider it done.

Good writing is a skill and can be developed

Writing well is a skill that can be honed with enough practice and time. I hope the
technical writing process discussed above has provided you with a framework to get
better at technical writing. However, consider it merely a suggestion. You're free to
tweak it and rearrange it as you see fit until you find something that works for you.
There is no "right way" or "wrong way" to write, but having a defined technical writing
process makes it easier.

1. Use Good Grammar

2. Write Concisely
3. Use the Active Voice
4. Use Positive Statements
5. Avoid Long Sentences
6. 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.