5 BEST PRACTICES FOR

TECHNICAL WRITING

Technical Writing is basically writing a clearer technical document. It

is simply taking high-level information and processing it into
digestible content for a specific audience.Technical Writing can
include a wide range of documents like instructions, presentations,
web pages, brochures, proposals, press releases, specifications,
reviews, reports, newsletters, and so on.

These documents, according to me, can be broadly classified into

two types:

1. Internal Documents – Documents that are for internal

organization, staff members, or internal project team members,
like Development Guidelines, Functional & Technical
Specifications for the Development team; Technical Guide for
the Support Team; Testing Checklist for the QA Team;
Training Programs for team members; Pre-Release and
Release Notes, and Process Manuals etc.
2. External documents – Documents that are public facing are
classified under the external documents.

 End-User Documents: Documents like User Guides, Pre-Release

and Release Notes, Training Programs, Instruction & Product
Manuals.
 Marketing Documents: Documents like White Papers, Case
Study, Press Release, Reports and Website content.
 Yes I know, at first, it may be overwhelming to see so many different
types of documents. But each document uses a similar writing
process and draws on an established set of skills. If you develop a
process, you can apply it to any technical document you are
creating.

 In this blog, I will be sharing 5 best practices which you can use at
the ready when you begin with your technical writing project.

1.    Know Your Audience

Analyzing your audience guides the intent of writing and determines
how complex or how simple the piece should be and how much the
content level should be.

Here are a few basic principles that you can follow:

 Identify your target audience – Identify who you are addressing

your document to, like – programmers, project managers,
executives, designers, marketing people, testers, end user, support
team, and admin team, etc. So, if possible, pick just one target
group of people and write for them.
 Know the culture of your audience – Determine what your target
audience already knows and what they need to learn. You must
also be aware of the ways in which your audience uses
documentation, and when. What language does your audience
speak-technical, or marketing, or design? What other kinds of
documents do they use, and how? Does a paper document make
sense, or would a presentation be more appropriate? You want your
document to integrate into your audience’s culture, not disrupt it.

Let us see a scenario to understand it better.

For a Mobile Application, while writing a technical specification

guide for developers, it will contain functional requirements, non-
functional requirements, business scope, technology stack,
infrastructure requirements, etc. However, while writing a public-
facing user guide, it will only contain Instructions and the User
Interface related content for the end customers. So this means for
the same application, you can make two entirely different
documents depending on the type of audience.

2.    Plan your document

This may seem obvious but spending time up front on planning can
reduce the actual writing time. Create a list of all the tiny actions you
need to take towards your goal.

Prepare a schedule to organize below pointers:

1. Collecting Data – Collect appropriate data before starting the

documentation so that you know what the user already knows
and what you need to tell them next.

Asking questions is an art and if you want to collect data and

simultaneously build up knowledge, you need to know WHO to
ask, WHAT questions to ask and WHEN to ask. Then you also need
to record the answers from others, so you build up a sort of FAQ
database for yourself.

It will be great idea to plan the document skeleton virtually in your

mind while you are collecting the information.

2. Drafting – Start writing what you know from what you

gathered. When drafting procedures, do a self-review to make
sure you can perform each procedure as you have written it.

Above all, keep the user in mind. While preparing, try to predict the
questions that may raise in the mind of the user. Users must be able
to easily understand and navigate through the content.

3. Reviewing – Typically, a Subject Matter Expert (SME) reviews

the first draft and the final draft of the document. Depending on
the type of content you are developing, however, you may
want the SME to check individual sections or topics.
4. Revising – Now that your first draft is ready, set up a peer
review to test the accuracy. Again, make sure the content is
presented in a way that makes sense for your audience.
5. Editing – In this phase you need to make sure the language
has a logical flow and the content is complete and consistent.
Having a second set of eyes on the content can increase both
the credibility and professionalism of the entire piece.

 Tip: Always start your document on a blank page.

3.    Gain Technical Knowledge

A technical writer must understand the subject and the purpose of
the document.

At first it is required to gather the prerequisite information by –

 Studying existing material from the knowledge repository
 Interviewing SMEs for KT or any query
 Using the product

Simultaneously it is a good practice to search the internet for online

videos and other relevant material to understand technical jargons.
Online content and videos will be very useful in the case when you
need to prepare a new document from scratch. This will not only
help you enhance your technical knowledge for that domain but also
guide you to grow in the project.

4.    Make it Interactive

The writing should be straightforward, to the point, and as simple as
possible to make sure the reader understands the process or
instruction. This at times may appear as simply a list of steps to take
to achieve the desired goal or may be a short or lengthy explanation
of a concept or abstract idea.

Follow the tips below to make your documents visually appealing

and interactive:

 Structured – Document formatting is one of the most important

elements in readability for end users. A document can be frustrating
to read and absorb if it is not structured into a clear hierarchy of
information. The simplest way to structure the documentation is to
organize it by groups. Use headings and sub-headings, Table of
Content, and hyperlinks (internal to the document and/or external).
 Typography – Font brings character to the document and varying
font sizes can help to draw reader’s attention as well. Also,
emphasizing headings, titles, and important takeaways to stand out
on the page can be effective.
 Color-code your notes – Adding a splash of color to the important
topics helps to make the information more readable and easier to
retain.
 Visuals – Things like diagrams, workflows, flow charts, highlighted
notes, and other visual aids are often great ways to associate and
remember key concepts.

5.    Follow Grammar & Writing Rules

When you speak and write, you must put the words in the right
order so that people will understand what you are saying or writing.
Rules make people feel comfortable.

We have listed down few ground rules for writing:

 Use active voice.
 Convert the passive voice sentences to active voice.
 Develop at least three strategies to make sentences clearer and
more engaging.
 Keep your sentences short. Use bullet points and numbered lists.
 Develop at least four strategies to shorten sentences.
 Create effective lead sentences for paragraphs.
 Avoid jargon.
 Focus each paragraph on a single topic.
 State key points at the start of each document.
 Understand the curse of knowledge.
 Break long topics into appropriate sections.
 Use commas, parentheses, colons, and semicolons properly.
 Use terminology—including abbreviations and acronyms—
consistently.
 Use spell checks to reduce the likelihood of spelling errors.
 Use several techniques to detect mistakes in your own writing.

Technical writing is centered on good planning and audience focus.

These tips provide different perspectives and practical methods to
accomplish your content goals.

Write to us to know more about our services and next time we

speak about how to go about playing it right with your API
documentation.