Off shoring of Documentation: a survey

Today, many software product companies have a base in India. A huge pool of talent, low wages, and an English-speaking population made India a great outsourcing destination. In the past few years, technical writing too transitioned to India for the same aforementioned reasons. If you are a technical writer working in the onsite-offshore model, please tell me how your experience has been. What are the challenges that you face? Are you satisfied with the job content? Please participate in this informal survey. Offer your feedback through the comments link on this blog or write to me at suman (at) Sumankumar (dot) com.

I look forward to hearing from you. Do pass the word around!




Write to me: Suman[at]sumankumar[dot]com

Read More

Writing SI units and symbols

Quite a few of us do not write the SI units correctly. If you are a Physics or Chemisty student, and still remember what you studied in school, you'll know the importance of getting your units and symbols right.

Important in SI:

1. The short forms for SI units (such as mm for millimeter) are called symbols, not abbreviations.
   
   
2. SI symbols never end with a period unless they are the last word in a sentence.
   
   
   
   
   
   • RIGHT: 20 mm, 10 kg
     
     
   • WRONG: 20 mm., 10 kg.
     
     
   
   
   
3. SI symbols should be preceded by digits and a space must separate the digits from the symbol.
   
   
   
   
   
   • RIGHT: It was 300 mm wide. The millimeter width was given.
     
     
   • WRONG: It was 300mm wide. The mm width was given.
     
     
   
   
   
4. Symbols always are written in the singular form (even when more than one is meant).
   
   
   
   
   
   • RIGHT: 1 mm, 500 mm, 1 kg, 36 kg
     
     
   • WRONG: 500 mms, 36 kgs
     
     
   • BUT: It is correct to pluralize written-out metric unit names: 25 kilograms, 250 milliliters
     
     
   
   
   
5. The symbol for a compound unit that is a quotient of two units is indicated by a solidus or by a negative exponent.
   
   
   
   
   
   • RIGHT: km/h or km·h^-1 (for kilometers per hour)
     
     
   • WRONG: kmph or kph (do not use p as a symbol for "per".)
     
     
   • BUT: It is correct to say or write "kilometers per hour".
     
     
   
   
   
6. The meaning of an SI symbol can be changed if you substitute a capital letter for a lower case letter.
   
   
   
   
   
   • RIGHT: mm (for millimeter, which means 1/1000 of a meter)
     
     
   • WRONG: MM or Mm (M is the prefix for mega, which means one million; a megameter is a million meters)
     
     
   
   
   

Links:

potsdam.edu

poynton.com

lamar.colostate.edu


Write to me: Suman[at]sumankumar[dot]com

Read More

Travails of a tech writer

Lot of people ask me what I do for a living. When I say 'Tech writer.' they go, 'What's that?'. And I explain,

'What do you do when you are stuck with MS-Word or Excel?'

'Call the guy that sold me the computer?'

And I'd hide my exasperation and pain,

'No, I mean, it is 2 a.m. and you can't call anyone.'

'What's the big deal? I'll call the next morning, but hey,you haven't told me what you do as a tech writer man.'

And I'd resign saying, 'I write help. Like when you hit F1 on MS-Word, you know?' And my audience would groan, 'ohhhh! Never read that stuff.' A pause. And, 'Is that it?'

There. Do you see my misery?

My audience includes lay people, software engineers, undertakers, tea-tasters, musicians, and my dad. Phew. All you guys, read this:

God I hate writing help files. I'll never be able to be a technical writer. How do those people do it? There are actually technical writing sites that are devoted to the love of the profession. I seriously admire these people. It takes nothing but love and hard work to be good at this (much like C++..?). And all I'm trying to do is make a simple help file on The Regulator. Geez. You'd think I'd have done it by now, 4 days after starting, but no. I only have like one page and a basket full of chocolate wrappings(kidding... we're trying to have the least amount of chocolate available in the house, specifically for situations such as this). So. any suggestions? anyone else wants to help me write this thing? I promise a serious credit in the about :)



To be honest, I've never had to do this before. Sure, I've written many technical documents, but documents that say “click this then you'lll see this so click that to get this” are simply ....ugh!

(via rosherove)






Write to me: Suman[at]techwritersindia[dot]com

Read More

Finding the voice

Excerpt from LOUIS MENAND's review of Eats, Shoots & Leaves: The Zero Tolerance Approach to Punctuation” (Gotham; $17.50), by Lynne Truss.

"Does this mean that the written "voice" is never spontaneous and natural but always an artificial construction of language? This is not a proposition that most writers could accept. The act of writing is personal; it feels personal. The unfunny person who is a humorous writer does not think, of her work, "That’s not really me." Critics speak of "the persona," a device for compelling, in the interests of licensing the interpretative impulse, a divorce between author and text. But no one, or almost no one, writes "as a persona." People write as people, and if there were nothing personal about the result few human beings would try to manufacture it for a living. Composition is a troublesome, balky, sometimes sleep-depriving business. What makes it especially so is that the rate of production is beyond the writer’s control. You have to wait, and what you are waiting for is something inside you to come up with the words. That something, for writers, is the voice."

Write to me: Suman[at]techwritersindia[dot]com

Read More

Oxford Plain English Guidelines

One of the guidelines is:

Commandment: Test with a panel of typical users – Give the draft instructions, and any product associated with them, to a focus group of typical readers. Watch them trying to use the instructions. Observe any false moves they make. Discuss with them how they got on. Ask them about any misinterpretations. Redraft the instructions in the light of what you find.

Ah!Usability testing of end-user documentation. How many of us do it?

Read all the guidelines at AskOxford site
Write to me: Suman[at]techwritersindia[dot]com

Read More

FAQ from Gregg Reference Manual

Questions and suggestions from users of The Gregg Reference Manual


Write to me: Suman[at]techwritersindia[dot]com

Read More

Wanted: Sr Technical Writer for Informatica Corporation

Location: Bangalore


Corporate Headquarters: Redwood City, CA


Contact: Thao Diep, tdiep@informatica.com





Job Description

Responsible for writing documentation to support our PowerAnalyzer and PowerCenter Connect product lines. PowerAnalyzer is a business intelligence tool that helps decision makers access, analyze, and share enterprise data. PowerCenter Connect products enable integration to ERP systems such as SAP and PeopleSoft, CRM systems such as Siebel, and messaging systems such as IBM MQSeries. As a Senior Technical Writer at Informatica, you will be required to write new manuals and update existing ones. You will be responsible for delivering high-quality printed manuals, online help, release notes, and webzine articles on time.

Responsibilities


Plan, develop, and write highly technical information (concept, task, and reference) that describes the functionality of our PowerAnalyzer and PowerCenter Connect products.

Maintain schedules for specific products and communicate documentation status to documentation manager.

Edit documentation for completeness, style, and accuracy to ensure it reflects Informatica's commitment to quality.

Mentor new writers.





Qualifications

• 3+ years technical writing experience (software).
• BA/BS (English, Journalism, Linguistics, History, Computer Science).
• Experience writing about a BI tool (Microstrategy, Business Objects, Cognos).
• Working knowledge of business analytics (BS in Business or similar work experience).
• Working knowledge of data warehousing, dimensional modeling and star schemas, web portals, web servers, application servers, and wireless protocols.
• Familiarity with databases, Java, SQL, ERP software, CRM software, and XML.
• Experience with FrameMaker, Web Works Publisher, DreamWeaver, or HTML.
• Excellent analytical and written communication skills.
• Excellent leadership and project management skills.
• Ability to quickly learn technical information.
• Ability to meet deadlines and help others meet them.
• Ability to multitask, prioritize, and develop schedules.

Write to me: Suman[at]techwritersindia[dot]com

Read More