Technical Writing ToolBox

A Blog on Technical Writing

Category Archives: Whatis

Difference between Literary Writing and Technical Writing

3 Comments Posted by Gurpreet Singh on September 18, 2013

What_is_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.

Technical Writing ToolBox Readership Survey

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

Gurpreet Singh fights the wind chill and -24 degrees winters in Toronto, Canada.

Dear Reader,

I’m curious to know about you. Really!

Humans, in general, are curious beings. This is clear by the fact that About me is one of the most regularly viewed page on my blog. You like to know about me. And I would love to know more about you!

This is a very unscientific survey to find out the demographics of my blog readers. This survey will only takes a minute or two to complete and will help me in writing content that interests you.

Please take a moment to fill this survey. Thanks in advance for your time.

Review, Whatis Readership Survey

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.

Pomodoro Technique: A Recipe for Increasing your Writing Productivity

10 Comments Posted by Gurpreet Singh on May 6, 2012

Pomodoro technique is a time management technique developed by Francesco Cirillo in the late 1980s and is quite effective in increasing work productivity. I’ve experimented with the Pomodoro technique and have received extremely positive results in increasing my own writing productivity.

What is the Pomodoro Technique?

Image Credit: Luca Mascaro/Flickr

“Pomodoros” is an Italian term which means tomato. Pomodoro technique uses a timer to break down periods of work into 25-minute intervals called ‘Pomodoros’ separated by breaks.

The pomodoro technique is named after the tomato-shaped kitchen timer that can be used to track your writing sessions.

TextCrawler- Search and Replace Text in Multiple Files

5 Comments Posted by Gurpreet Singh on April 30, 2012

Program Name: TextCrawler

Use: Search and Replace Text across multiple files

Cost: Freeware

Works on: Windows (XP/Vista/7)

Detailed Review: Read here (opens in a new window)

Download Link: http://www.digitalvolcano.co.uk/content/textcrawler/tcdownload

I’ve often faced disappointment from various Help Authoring Tools when it comes to a simple text operations such as search and replace among multiple files. Most of the time I had to create a small macro that could do the job, or had to manually search and replace the text in html mode. Few years back I started using specialized text editors such as Crimson Editor and Notepad++ to do the job. They were good but limited in their functionality and took a lot of time to do the job.

I recently started using TextCrawler and have been pretty impressed with its ability to find and replace text among multiple files.

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.

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).

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?

Introducing Google Tap- Tap into the future of Technical Writing

11 Comments Posted by Gurpreet Singh on April 1, 2012

Technical Writers often burn midnight oil typing long, lengthy, and often boring documents for their bored employers.

Let’s face it- typing is hard work considering that you need to work with 26 characters keys and five helper keys (alt, spacebar, shift, capslock and shift). Wouldn’t it be cool if you can reduce your work by typing from only two keys instead of 31 keys, usually required for normal typing?

Google, once again, comes to your rescue by providing a technology called Google Tap (aka Gmail Tap) that can make your dreams come true. With Google Tap, it’s time to move beyond the QWERTY keyboard. Google Tap allows you to ~~type~~ tap a letter, email, or a user manual with just two keys!

What is API documentation?

18 Comments Posted by Gurpreet Singh on March 27, 2012

API documentation, also known as Programmers documentation, is a deliverable of technical writing in which a technical writer develops instructions about how to effectively use a software API, hardware (SCPIs) or web-API.

What is an API?

API is an acronym which stands for Application Programming Interface. An API is a set of predefined rules and specifications that a software program can follow to use the services and resources provided by another software program. In other words, API is a kind of communication channel through which two separate programs can communicate with each other and share each others service and resources.

A typical firmware-controlled device, a television remote control. Consumer products like this have been using firmware since the 1970s. (Photo credit: Wikipedia)

For example, take the example of a TV. You have a hardware button on your TV which turns it ON/OFF. Now let’s say you want to turn ON the TV from a distance. You just press the ON/OFF button on a remote control and the TV set mimics the command given by the remote control. This is how API works! Think of TV as a Software Program having services and resources, and the TV Remote control as another software program which use these resources. The method (or radio/infrared waves) through which a remote control communicates with a TV set is an API.

Types of API?

APIs can be created for a broad set of software programs such as Operating Systems (OS is a big program, right?), software applications, programmable hardware and software libraries so that other software programs can use the services (if any) provided by these programs.

Depending upon the medium and services it provides, APIs can be divided into three distinct groups:

Software API
SCPI (Hardware API)
WebAPI

Software API are APIs that provide access to the functions or services provided by another software.

For example, Microsoft Windows has a number of APIs available in its Shell32 library. One of the commonly used API is SHExitWindowsEx which can be used by a software program to log off, shutdown, restart, forced shutdown or power off the Windows operating system.

The syntax call is:

SHExitWindowsEx n (where n can take values of 0,1,2,4 and 8)

0 = Log Off
1 = ShutDOwn
2 = Restart
4 = Forced
8 = Poweroff

SCPI is an acronym which stands for Standard Commands for Programmable Instruments. SCPI (commonly pronounced as ‘skippy’) is a set of predefined rules and specifications which is used for controlling programmable test and measurement devices. What API is for a software program, SCPI is for a programmable test and measurement devices.

For example, “*IDN?” is a standard SCPI command used in many interfaces (GPIB) and programmable instruments to fetch basic identification data from a device.

WebAPI are APIs that provide access to the functions or services provided by a web-service (or a website). In its simplest form, a WebApi is typically a defined set of Hypertext Transfer Protocol (HTTP) request messages,which may contain a definition of the structure of response message as well. The response of a WebAPI is usually written in a Markup language such as Extensible Markup Language (XML) or JavaScript Object Notation (JSON) format.

What is API Documentation?

API documentation is a deliverable of a technical writer which describes, with examples, how to effectively use a Software, Hardware or Web API. It requires a thorough understanding of the API, its arguments, its return type and the languages and interface it supports. Technical Writer having programming knowledge often create instructions, procedures and example for APIs that ships along with a software product.

Have you ever created API documentation? Do you find it interesting? Leave a comment and let me know.