Technical Writing ToolBox

A Blog on Technical Writing

Category Archives: Article

Technical Writing: The 37th Best Job in 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?

Read more >>

Advertisements

What is Audience Analysis?

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

Read more >>

Make your Sentences Slim (by removing 35 Wordy Phrases)

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

Brand Damage due to Bad Translation

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.

Read more >>

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

Three CommasWhat 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.

Read more >>

The Art of Concise Writing

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?

Read more >>

What Technical Writers can learn from Square Watermelons?

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.

Read more >>

The Controversial discussion about Outsourcing and Technical Writing

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.

Read more >>

The Love-Hate relationship between Technical Writers and Software Tools

 

FrameMaker, MS Word, PowerPoint, Excel, Quark Express, Visio, SnagIT, RoboHelp, Madcap Flare, Author IT, Acrobat, PageMaker, Wiki, XMetal, Oxygen… more and yet more tools.

Read more >>

Culture Shock: A Technical Writer’s Viewpoint

Gurpreet took this picture of a beggar while experiencing a culture shock in the streets of San Francisco.

No people come into possession of a culture without having paid a heavy price for it.”- James A. Baldwin

Technical Communicators often have to travel overseas for an extended period of time for work, training, and higher education. Gurpreet Singh describes the stress, also known as culture shock, caused by living in a different culture and its different stages with his own personal experiences. He took the above photo while experiencing a culture shock in the streets of San Francisco.

What is a Culture Shock?

Culture Shock is defined as the stress or a feeling of disorientation, experienced by someone who is suddenly exposed to a different culture. Most people experience culture shock when they live overseas for an extended period of time.

Read more >>

How to set your Freelance Writing Rates?

Photo Credit: Dilbert.com

Writers working on a freelance basis often face difficulty in deciding the method to provide a quote to their clients. Whether they should charge on the basis of pages, assignment, or, hour et al.  I will describe a few payment methods I’ve used as a freelance technical writer.  Only you can decide the payment method suitable for your freelance writing assignments as each assignment is different.

Freelance writers, many times in their career, wonder about the method they should use for their writing assignments. While it seems an easy and good way to use one particular method for all types of writing assignments, the variety of projects having different requirements make it almost impossible to use a standard payment method.

Read more >>

Introducing Google Tap- Tap into the future of Technical Writing

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!

Read more >>

10 Twitter hashtags for #TechnicalWriters

 

Twitter  is becoming a useful media for sharing information. Many technical writers (including me; my twitter id is @gurpreetwrites) have started using this media to spread information, news, and sometimes their opinion about technical writing. Tom Johnson also blogged about using hashtags on mobile.

The # symbol, called a hashtag, is used to mark keywords or topics in a Tweet. A hashtag makes it easier to follow a particular profession (such as technical writing or software development) or an event (such as conference).

Read more >>

How to add a Captivate Video in RoboHelp?

A picture says a thousand words. What about a video? How many words can you save by adding a video to your documentation?
This tutorial explains how to add a Captivate video in RoboHelp.

Approach #1: Use Captivate and RoboHelp as two separate software

Open Captivate. Create a video in Captivate and generate the output as Flash (SWF). Make sure that you have checked the option of “Export to HTML” since not selecting this option may generate an output that will not display properly in a web browser. You can generate the flash output using File > Publish or by using the keyboard short-cut Shift + F12.

Open RoboHelp and import the html page you just generated (as if you are importing a normal html page) in RoboHelp. You can do this by File > Import > HTML File. 

Alternatively, you can also add a Captivate video using RoboHelp toolbar. Click Captivate icon in the Objects toolbar. This displays a dialog box where you can directly select the swf file.

Note: If you cannot see this toolbar then it may be hidden.You can display it by View > Toolbars > Object.

Approach #2: Work within RoboHelp environment

Sometimes you want to generate quick demonstration videos within RoboHelp environment without opening Captivate. RoboHelp provides an option to add a captivate video without the need of leaving RoboHelp environment.

Select View > Pods > Project Manager. The Project Manager pod appears. Right click on Project Files, select New > Adobe Capotivate Demo.

A dialog box appears. You can add name of the video and the corresponding html page.

Click OK.  Create the Demo and close the Captivate window. Since you started the process within RoboHelp environment, there is no need to import the video.

You can add this page in TOC, or create a link to this page from other pages in the project.

When a user view the page the video automatically starts.

Note: Sometimes, the automatic play becomes a bit annoying. If you want the video to start after a user clicks on it, select Edit > Preferences in Captivate, select Start and End preferences, deselect the option to Auto Play. This will publish a play button inside the video and a user will need to click on the video to start it.

What do you think about this tutorial? Do you use a different approach to add captivate videos in RoboHelp? Leave a comment and let me know.

Quality Metrics for Technical Writers

Overview

The simple definition for metrics would be the methods or ways used by companies to judge success and/or failure of their work standards by the scientific measurement of data usually gathered from specific tasks, such as production, testing, documentation and so on.

If we look at documentation, which is a complex task that includes several subtasks such as writing, editing, reviewing and so on, we can gather the common errors in each of the processes to remove them from the entire documentation cycle. This error removal automatically improves the overall performance of the organization/individual involved in the creation of documentation.

Quality vs. Productivity Metrics

Quality metrics, as suggested by their name, are metrics of the statistics about the quality aspect of documentation. Productivity metrics are more concerned with the productivity or the rate of production of words rather than the quality aspect.

These two are quite different from each other as they map two distinct areas of the documentation sector: namely, quality and quantity. Each organization/individual already works with some kind of metrics, whether they know it or not. There is a complete subject devoted to the processes used to gather and analyze such statistics with the name of Operation Research (OR).

OR is a very interesting field and is a must for people who are interested in the usage and benefits of metrics of any kind, not just documentation. The power of these statistical analyses can only be visualized correctly if you create one real-time analysis of your own organization.

Documentation Metrics Formula

Now, coming back to the original subject of quality and quantity (aka productivity) in documentation, we use these metrics allthe time. If you estimate, based on your previous experience, that a user manual will take x number of hours, then that data has come (indirectly) from your productivity metrics.

If you write down your experience with different projects, such as user a manual of this kind, will take x1 hours per page, the installation guide of y type will take x2 hours to complete, the help file of c type will take x3 hours and so on, then it will constitute a simple documentation productivity metric for you.

This metric simply reflects how soon the work will be finished depending upon the complexity of the task. This is a global method used for estimation of all kind of projects, and we can apply it to documentation projects also.

Benefits (or The Catch!)

The benefits of such productivity metrics are incredible. Let’s say that you are working as an independent consultant like me and get a request for providing quotes for several different kinds of projects every month. One method is to analyze the kind of project and then place a bid based on your experience.

This can be quite dangerous, particularly if you are inexperienced, as estimation can very easily go to values much less than the actual time needed to complete the project. Even experienced consultants often make mistakes in estimating the efforts required for a document. This means that you will work more for the same money due to the faulty estimation. So this method is not scientific enough to be applied to projects, as the error margin is quite high.

On the other hand, let’s say that you create productivity metrics for yourself based on different aspects of documentation and your working speed. You can estimate the time needed to complete a project scientifically by the use of this productivity metric, which you already created in the past.

Yes, a considerable amount of time is needed to first record the data, analyze the statistics and create the metrics, but it is a wise decision that you can make for reducing the forthcoming work in the form of estimates for different projects.

Quality Metrics & Reading Scores

Talking about the quality metrics, it is simply a measure of how useful the document is for the intended audience. Please note that I used the word “intended” audience here, as a document scoring high on your quality metrics for IT managers may fall below the passing mark for say 12th grade students. Each quality metric is limited by the audience it refers to. So in most companies, the generation of different quality metrics for different audiences is common.

The quality metric is usually based on a number of different aspects of documentation such as:

  1. Readability of the overall document (Flesch reading ease)
  2. Grade level required to read the document (Flesch-Kincaid grade level)
  3. Time required by a typical audience subset to read and understand the content of document
  4. Usability in terms of problem-solving techniques
  5. Number of editing cycles required to finalize the document
  6. Spelling/typo errors
  7. Time spent in hours to complete the document from scratch
  8. Human resources required in the preparation of the documents
  9. Compliance with style guides such as MMOS, APA, MLA, Harvard, and so on

So if your intended audience is normal people, you must achieve at least a score of 50 or above in the Flesch reading score. In the Flesch reading score, the scores usually denote the complexity of the documentation and what grade education is required to read and understand the component of documentation. The values are as follows):

Flesch Reading Score

So, if you are writing user manuals for 12th grade students, then you must make your documents less complex by using simple words instead of complex ones, producing a Flesch reading score of 35-50, preferably above 40.

I see many listserv messages that have a Flesch score of less than 15, which is not good for the average reader. By using difficult words, the messages are not highly effective since few may understand the content. It might be good to check the reading ease of your posts or documents for the reader’s benefit.

This entire post has a Flesch reading score of 46.7, which means that it can be understood by a majority of people who have a high school education. There are several other factors that you can put into quality metrics, but for now these points will guide you to search for more complex methods to be used in such metrics.

This article was published in the STC Management Special Interest Group (SIG) newsletter- Directives.

What do you think about this article? Have you ever thought about creating documentation metrics? Leave a comment and let me know.

A day in a Technical Writer’s life

Good Morning!

My name is Gurpreet Singh and I’m a student of technical communication. I’m pursuing a yearlong post graduate certificate in technical communication from Seneca College, Toronto. Before joining this program, I worked as a technical writer for eight long years in New Delhi, India.

A lot of people in my class asked me to explain how it feels to work as a technical writer. They wanted to know if technical writing is exciting or does it becomes boring after spending few years down the line.

The interesting thing about technical writing is that technical writers enjoy a multitude of roles and responsibilities, which includes delivering documentation for a plethora of products while meeting stricter deadlines. Thus, no two work-days are alike. Each new day starts with a fresh set of challenges. These challenges make the day and the life of a technical communicator all the more exciting.

I work used to work as a Technical writer in the hi-tech Semiconductor domain, and develop documentation for a wide array of commercial EDA (Electronic Design Automation) software.  Technical writers in my organization are referred to as Learning Product Engineers (LP Engineers). Here is a snapshot of my day when I was working as a technical writer:

My day usually starts with a morning scrum meeting. Each meeting usually lasts for 15 minutes. During the meeting, each team member reports about what they accomplished on the previous day, issues or major showstopper, and the plan for the day of the meeting. These meetings are also called as stand-up meetings, because the goal of these meetings is to keep them brief and productive. Hence, all members attend these meetings standing instead of sitting.

Every Monday, we have a longer weekly meeting with our manager to discuss the status of projects, issues, challenges, and so on. Team meetings also provide a forum to discuss team-specific internal documents. For example, the Style Guide. Discussions about purchasing new tools also take place during these meetings.

Monday also happens to be the planning day when we set plans for the week including meetings with subject matter experts (SMEs) (blocking time in their MS Outlook calendar is essential!), training calendar for self, and scheduling meetings related to various internal and external projects.

Rest of the week is usually a good mix of long write-edit review cycles, meetings, and training.

A typical day in my work life looks somewhat like this:

  • Check corporate emails with a cup of hot Cappuccino: I receive most of the emails from my R&D team based in Santa Clara, California. Due to the time zone difference, they are 12 hours behind us (my night is their day). So, while I’m having a sound sleep, my colleagues continue to develop new features during their day, and send me various documentation requests.
  • Listen to voicemails: Few of the SMEs I work with hate writing long emails. Hence, they leave voicemails for me, which may include information about a new feature. Works great!
  • Attend documentation meeting: As a mentor, I attend documentation meetings to troubleshoot any issues faced by junior writers, or to redirect them to a specific group/person.
  • Moderate Wiki pages: We use Confluence Wiki to author, review, collaborate, and publish technical documentation. A nightly build generates chm, html, and pdfs, directly using the content from Wiki. The beauty of this system is that SMEs (R&D, QA, Sales, Marketing, and Management) can directly edit and add content, instead of routing every request to a LP Engineer. I edit the updated or the newly added Wiki pages for grammatical mistakes, accuracy, and adherence to our internal writing style sheet.
  • Install new software build: Every morning a fresh software build is made available in the repository. After installing, I usually play around with the application to check if there are new enhancements/fixes that are displayed in the GUI. Though, I often get documentation requests in form of emails or bugs logged in Bugzilla, it is not uncommon to detect a new setting popping in the new build.
  • Close documentation bugs/New Feature documentation: Every day I run a query in Bugzilla to check new documentation bugs/requests filed for me (New feature documentation requests are also filed as bugs). Some bugs need 5 minutes of effort while others (majority) may require an effort of couple of hours. Occasionally, I have bugs (enhancement requests) that might take a few weeks to get completed. Zero bug report is what my eyes dream of seeing everyday.
  • Lunch: Home cooked food with a few friends in the office cafeteria: A major stress buster for my day!
  • Research using internal/external networks: My work involves documenting extremely technical products for an audience that comprises Engineers and Scientists (who prefer no-nonsense technical documentation). Thus, I try to learn as much as I can about a new feature before I write about it.
  • Check the Doc Project Schedule: Since I work on multiple projects, I keep a tab on all the deadlines (daily/weekly) and try to make sure that everything runs smoothly. In case of a slippage in the schedule, I schedule a meeting with the project manager to mitigate any impact by lowering the scope, or by requesting a fresh deadline.
  • Conduct Trainings: I often get requests from various teams/groups within my organization to conduct training on Wiki, writing, presentation skills, and Lean/Six-Sigma topics.
  • Conduct Lean Meetings: As a Lean/Six-Sigma champion for my team, I lead few internal projects to reduce technical writing process timelines, reduce documentation defects, and improve productivity, and to find areas of automation with our technical writing tools or processes.
  • Coffee Break: Catching up with an old friend with a hot cup of coffee is nothing less than having an apartment in the heavens!
  • Conduct Toastmasters Sessions: Being the president of our Corporate Toast-masters Club, I often conduct the toastmasters session that help our club members (from various departments and placed at different levels in the hierarchy) to develop their presentation, public speaking, and leadership skills. I’m an award winning humorous speaker!
  • Conduct Peer Review: Every documentation project in my team has an author and a peer reviewer. The peer reviewer acts as a dummy user and tries to validate documentation for usability and functional errors, which are often unnoticed by the author. I review two projects in my team. Similarly, my own projects get reviewed by two different authors. I always get amazed by the fact that how easily others can catch errors in our work, which we fail to see, even after several cycles of internal testing.
  • Say Sayonara to work and head back to home-sweet-home!

Wait: Meeting with the Santa Clara R&D team is at 11.30 pm, and it extends well past midnight: Another disadvantage of the global work environment. But hey, it is still fun to be a technical writer working with global teams!

What do you think about my workday? Is it similar to yours? Leave a comment and let me know 🙂

What is API documentation?

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

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.

%d bloggers like this: