Technical Writing ToolBox

A Blog on Technical Writing

Category Archives: Elements of Technical Writing

Visual Chemistry- Interaction of Text and Graphics

1 Comment Posted by Gurpreet Singh on July 16, 2012

Visual Chemistry

Technical communicators often use graphics with written procedures to communicate complex ideas.

Illustrated text often delivers better information that is more readily comprehensible to readers. However, if illustrations are merely used as a decorative item then they do not convey worthwhile information, and have a significant impact on readers. Readers are benefited when illustration and text work together to put forward a complex idea in a simple way.

Higher Education in Technical Communication- Is it worth it?

11 Comments Posted by Gurpreet Singh on July 3, 2012

Technical Communicators are passionate about learning and often ponder on the question of higher education in the field of technical communication. The dream of gaining knowledge and credibility by pursuing higher education in technical writing often eludes technical writers at all levels of their career.

Gurpreet’s First Day @Seneca College

I worked as a technical writer for eight years in New Delhi and recently took a sabbatical to pursue a postgraduate certificate in technical communication from Seneca College, Toronto. The term sabbatical (from Latin ‘sabbaticus’, from Greek ‘sabbatikos’, from Hebrew shabbat, i.e., Sabbath, literally a “ceasing”) means to take a break from work for an extended period of time to pursue a goal. In modern times, several professionals have started taking a sabbatical to pursue higher education in their chosen disciplines.

My STC Presentation on Effective Presentation Skills

Leave a comment Posted by Gurpreet Singh on June 15, 2012

I conducted a skills development workshop for STC India (New Delhi) chapter two years ago. The workshop was warmly appreciated by the participants. The slide along with text transcript is available in this post.

Though the presentation shared in this post is two years old, the basic principles of presentation has not changed much in the past hundred years.

7 causes of Inefficient Writing

8 Comments Posted by Gurpreet Singh on June 7, 2012

Few weeks back I talked about three external factors that gives birth to inefficient documents. Writers either have no or very less control over these factors. However, this is not always the case. In fact, usually a writer makes documents inefficient if they fail to remove common writing mistakes from their work. Let’s look at seven factors that cause inefficient writing even when the content is technically accurate and the grammar is perfect:

Difference between Task, Concept, and Reference topics in DITA

9 Comments Posted by Gurpreet Singh on May 31, 2012

Task, Concept, and Reference in DITA

Note: The content on this page is based on work done by Bernard Aschwanden of
http://www.publishingsmarter.com and is used with permission.

The Darwin Information Typing Architecture (DITA) specifies three basic topic types: Task, Concept, and Reference. However, people often get confused about these three types. Our cool (and knowledgeable) professor Bernard Aschwanden (he is an expert in DITA!) gave us an interesting exercise to differentiate between the three topic types in DITA.

How to write a Technical Autobiography?

10 Comments Posted by Gurpreet Singh on May 29, 2012

Technical Autobiography of Nikola Tesla

When I joined Seneca College (Post Grad) Certificate in Technical Communication, the first (informal) writing assignment we received was to write a technical autobiography (worth 10%) in the TCN700 (Technical Writing I) class.

Wait, I hear you saying that the term ‘technical’ and ‘autobiography’ don’t go well together. You are in good company as most of us in the class at that moment thought on similar lines. It was only when our dear professor explained the concept of technical autobiography when we understood how important it is for a writing student.

10 Useful LinkedIn Groups for Technical Writers

5 Comments Posted by Gurpreet Singh on May 27, 2012

LinkedIn started out in the living room of its co-founder Reid Hoffman in 2002 and now operates the world’s largest professional network on the Internet with 161 million members in over 200 countries and territories. It is available in seventeen languages: English, Czech, Dutch, French, German, Indonesian, Italian, Japanese, Korean, Malay, Polish, Portuguese, Romanian, Russian, Spanish, Swedish and Turkish.

LinkedIn receives a new member after every half second. If you do not exist on LinkedIn then you are surely missing job and consulting opportunities available in this professional network. If you are present on LinkedIn, I invite you to get connected with me at http://ca.linkedin.com/in/gurpreettw.

Top 3 Serial Killers of a Good Document

8 Comments Posted by Gurpreet Singh on May 17, 2012

Don’t kill me- says your document!

Whether you are writing a user’s guide, online help, or an installation guide, you always strive to convey a meaningful message to your intended audience.

However, the message often gets diluted and becomes meaningless due to a number of reasons. Of course, a writer may not put enough efforts in making a message meaningful but most of the time several external factors contribute in killing the effectiveness of a document. Let’s look at the top three factors that kill a good document:

5 Free Online Tools for Distraction-Free Writing

7 Comments Posted by Gurpreet Singh on May 8, 2012

Last week I talked about the importance of distraction free writing and suggested five free desktop tools for distraction free writing. However, some of us cannot install any software in a workplace computer due to the mighty-IT department restrictions or often work on shared computers. If you find yourself in either of these scenarios then you can use an online version of a distraction free software.

An online distraction free tool allows you to write without any distraction. There is no installation required and it can work with any modern browser. Let’s look at five such online distraction free tools:

Update (19 Feb 2014): A reader comment pointed out that QuiteWrite, LightWrite and Writer are inaccessible.

1. Koi-Writer

Online Access: http://www.koi-writer.com

7 Useful Insights about How People Read Documentation

5 Comments Posted by Gurpreet Singh on May 3, 2012

Reading is a primary form of communication for most people and they have different habits of reading. Not surprisingly, different people read product documentation in different ways. But how do they read and why should we care about their reading habits?

A writer writes with a purpose. This purpose gives shapes to their thoughts and allows them to convert their body-less thoughts to words. A strong correlation exists between a writer’s purpose and use of the document.

Getting Rid of Misplaced Modifiers

7 Comments Posted by Gurpreet Singh on April 29, 2012

Modifiers are words, phrases, or clauses that restricts or provide additional information about other words, phrases, or clauses. Modifiers can be adjectives or adverbs. Modifiers that appear before the head are called premodifiers and modifiers that appear after the head are called postmodifiers.

We have a certain amount of freedom in deciding where to place our modifiers in a sentence:

We rowed the boat vigorously.
We vigorously rowed the boat.
Vigorously we rowed the boat.

Five Best Distraction-Free Writing Tools for your Desktop

14 Comments Posted by Gurpreet Singh on April 24, 2012

As a person who makes his living by writing, I have to admit that writing is hard work. And what makes it even harder are the constant distractions in our workspace. I’m not talking about noisy children, complaining in-laws, and constantly barking neighbor’s dog (although they all distract!). I’m talking about the constant electronic distraction on our computer screen.

Technical Writing: The 37th Best Job in 2012

10 Comments Posted by Gurpreet Singh on April 22, 2012

I always dreamed of becoming an astronomer- to see what no man has seen before. However my interest in learning and building complex systems encouraged me to become an Engineer and my love toward writing made technical writing a viable and exciting choice for my work. Which profession, other than technical communication, allows a person to use both his/her technical and writing skills at work?

What is Audience Analysis?

11 Comments Posted by Gurpreet Singh on April 18, 2012

In order to publish an effective help documentation, you must gather as much information as you can about your audience. For most technical writers, audience analysis is the first, and perhaps the foundation step, in developing documentation for an end-user while following a documentation development life cycle (DDLC).

Make your Sentences Slim (by removing 35 Wordy Phrases)

10 Comments Posted by Gurpreet Singh on April 17, 2012

Photo Credit: OnBloggingWell.com

One of the easiest way to achieve conciseness in your writing is by removing wordy phrases. Wordy Phrases are long sentences that can be replaced by a single word (or few words) without changing the meaning of a sentence.
Read more >>

Article, Elements of Technical Writing, HowTo, Writing Tips Concise Writing, Example of Conciseness, Short Sentences, Technical writer, Wordy Phrases, Writing Tip

Brand Damage due to Bad Translation

5 Comments Posted by Gurpreet Singh on April 16, 2012

Canada Government Immigration department ad in Hindi language having 5 typos (out of 18 words)

Canada Government Immigration department advertisement in Hindi language (Indian language) having 5 typos (out of 18 words)

I love studying in Canada. It’s a land of opportunity.

People in my class, College, and even strangers walking on roads of Canada are helpful (except for few weirdos I often encounter) and even Canadian Government supports many programs that help immigrants to adjust in the Canadian society.

Story of the comma family: The Oxford, Harvard, and Serial comma

19 Comments Posted by Gurpreet Singh on April 15, 2012

What is the Oxford comma?

The Oxford comma (also known as Harvard comma or Serial comma) is the comma inserted just before the coordinating conjunction (usually ‘and’ or ‘or’, and sometimes ‘nor’) in the last item of a list of three or more items. For example: This blog is dedicated to Jack, Jill, Red Riding Hood, Captain Kirk, and Spock.

The Art of Concise Writing

23 Comments Posted by Gurpreet Singh on April 13, 2012

“Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts.” – William Strunk in his classic text The Elements of Style.

What is Concise Writing?

Writers often strive to achieve conciseness in their work. But what exactly does it mean to be concise?

What Technical Writers can learn from Square Watermelons?

4 Comments Posted by Gurpreet Singh on April 10, 2012

Square Watermelons from Japan. (Photo Credit:Wikipedia)

For years watermelon lovers have struggled to fit the large round fruit in their refrigerators. In a country like Japan, where real estate resources are scarce, this problem gets amplified several times. Another problem they faced was trying to cut the fruit when it kept rolling around.

The Controversial discussion about Outsourcing and Technical Writing

7 Comments Posted by Gurpreet Singh on April 9, 2012

An auto rickshaw (aka a three-wheeler taxi) showing an ad of a call center training institute in the South Indian town of Madurai. Photo Credit : http://anticap.wordpress.com

Indian technical writing industry is often blamed for taking technical writing jobs away from North American markets. In various mailing lists, this issue raises its ugly head from time to time, starting a heated debate about the threat of outsourcing to non-English speaking countries such as India. Tom Johnson, in his article about technical writing jobs, considers outsourcing (of technical writing jobs to India) as a threat to the technical writing industry in North America.