Writers India: Technical Writing and Design Communication

This blog has moved...

2010-03-10T07:30:00.001-08:00

I have discontinued this blog and I will continue to write on Technical Communication at http://sumankumar.com Update your RSS feeds to http://sumankumar.com/blog/feed

Write to me: Sumank[at]gmail[dot]com

The Personable Manual

2009-02-24T01:07:00.000-08:00

Why do product manuals sound formal and stiff-upper-lipped? Why don’t users read manuals? These questions have haunted the hallowed precincts of Technical Writing for quite some time now. From what I have seen in Indian writers, I am forced to conclude that English Composition, as we were taught in school, is the culprit. Our merit was based on how verbose we were. They judged our style based on how ‘formal’ we were.

Take for example, the leave letter. I am sure you have written a few in school or college. Rewind and replay one of those leave letters. Right from the salutation (‘Respected sir/madam’) to the signature (‘Faithfully/Obediently yours’) it reeks of colonialism. And, we have yet to learn our lessons. In this age of globalization (or globalisation, to my stiff-upper-lip comrades), it is important to pay attention to the three Cs: Consistency, Context, and Culture.

The You
I have read manuals that say ‘you can perform this task…’ and in the next chapter add, ‘Users should back up data regularly’. Who is the ‘you’ and who is the ‘user’? Quite a few of my esteemed friends that are Technical Writers shy away from using ‘you’ in their manuals. Again, it is that skeleton in our cupboards (or closets, if you will, my American friend) called Colonial Composition that proves to be the stumbling block. I do not wish to debate on the aesthetic merit of using (or not using) ‘you’ in our manuals. The goal of your manual is to help users be productive. So let us stick to that story for now.

Let us look at an example:
1) If the system displays a blue screen, the OS should re-installed.
2) If your system displays a blue screen, re-install the OS.

Let us not discuss active and passive voice. Let us focus on the word ‘your’ that replaces ‘the’. Both statements offer the same instruction. If you took a poll with your users on which one they liked. I am quite sure they’d pick the one with ‘your’. Why? Because it is personable. The statement is talking to the user and thus telling the user ‘there’s something in it for you’ and urges action. There is no ambiguity (‘OS should be installed? By who?’). And, the ‘your’ statement costs less to Localize.

Also, it is important that your product offers a favorable emotional experience to your users. That is where the Colonial Composition fails. Ask any Interaction Designer and she’ll tell you how important Subjective Satisfaction is to the success of any design.

Personable Manual
Personable writing pays. What would you prefer to read?

"It is recommended that you upgrade your software."

"We recommend that you upgrade your software."

The latter engages you. It makes a convincing statement. It doesn’t hide behind the facade of passive voice, and it puts an arm around you and requests, like a friend, to do the needful.

There again, some of you might say ‘well, if we screw up, then because we used ‘we’ we may get into a soup.’

Let me reassure you here: 1) you don’t write for a contingency called screw-up. 2) You write to ensure your user increases her productivity. And 3) Whether you write in passive voice or active voice, if it is in the manual, you are liable.

Finally, being formal is overrated. Just because you are in business does not meant you have to be business-like in your manual. That is a sad misconception. You got to connect. You have to converse with your user. You need to engage and offer a positive emotional experience to your user. Else, the user will pick that phone and call Support. Now, that, in my book, ~~completely~~ obviates the need for publishing a manual. And, having a writer on board.

Write to me: Sumank[at]gmail[dot]com

Promoting Document Usage: Taking a leaf out of Business Directories

2008-11-21T01:54:00.000-08:00

You can argue all day that you know a customer that reads your manuals but my point is that most don't. It is a blessing in disguise for most of us: we get away with some really sloppy writing. But if you honestly want to help your customers but don't want to incur support costs, here goes:

Don't talk to them about your cream. Talk about beautiful, flawless skin. Didn't get it? No problem. Most software vendors bundle documentation or at least provide documentation online. And, most think their duty ends there. It doesn't. If it did, explain why customers still call up your Support Desk for information; the same information that your manual offers.

The explanation to this predicament lies else where: Business Directories. I used to be a Sales Rep for Tata Press Yellow Pages in Chennai (they call it InfoMedia now). After publishing and distributing the directory to users (all homes with a phone), they ran a publicity campaign. The campaign was meant to educate users on how Yellow Pages can help them. "Looking for an Architect? Look under Architects category in Tata Press Yellow Pages" Or something like that. The success of the brand depended on people using the product.

Do you promote the usage of your product documentation? I know the answer. Most of you don't. So what should you do?

Talk to your marketing/sales and support folks and send periodic e-mails to your customers. "Did you know that the Deployment Guide can help you customize the interface?" Or "Want to integrate MS-Office with your_product_name_here? See the Office Integration chapter in the Deployment Guide."

Also:
1) Track the kind of support calls you've been receiving
2)Identify common issues
3) Address them in your documentation
4) Highlight the fixes in your usage mail campaign
5) Start from step 1 and keep iterating!

I said track support calls instead of 'take a survey' because I don't believe in surveys. Surveys are the equivalent of you asking your dinner guests 'Hope you liked the food!' The answer is always yes, unless you have a socially aberrant guest who'd say 'Yuk. That food sucks!'

Think about it.

Write to me: Sumank[at]gmail[dot]com

Comics and Technical Communication

2008-09-01T23:39:00.000-07:00

As always Google breaks away and uses a comic strip to do a launch-promo for its - hold your breath - web browser! Ladies and gentlemen, say hello to Chrome.

Maybe, just maybe, comics can be used for Quick Start Guides? Place Mats?

Write to me: Sumank[at]gmail[dot]com

Tech Writing Manager? So What?

2008-05-08T22:29:00.000-07:00

One of the 'tech writing managers' wrote on the TWIN list about this 'exclusive' Google Group he'd created for 'tech writing' managers. Here's what I wrote in response:

One of my very good friends runs a small software product company in Chennai. When I walked into his new office for the first time, I was stunned: plush interiors, air-conditioning, and a 'CEO' cabin! I was impressed.

I visited him again after a few months and noticed that he was sitting 'with' the team. The cabin was empty and I found a huge couch in the place of the Teak wood table.
The girl next to him was watching a movie. The guy next to him was chatting on G Talk. And our CEO stood up and ushered me into the 'cabin'. I asked him 'you don't sit here any more?' He smiled and said, 'I realized that if I sat 'with' them they'd feel I am 'one of them' and that's key to the success of an R&D environment.' I couldn't agree more.

I asked him, 'What's with that couch?' My friend's smile stretched till his ears as he said, 'When one of us are tired or spaced out, you know? We go and take a nap in that former CEO cabin.'

Bravo! I am sure you'll hear about him and his company very soon. There's no way this company can NOT succeed! Anyway...

I am just curious:

How are management issues different in technical writing? Management is management, right? You hire and manage people. You supervise project execution. Um, oh! you motivate people. You take the team to the next level. whatever that means? What else? Every manager, be it managing a snack bar in Domlur or a NASA lab, does that.

Don't you think you are flouting a key management principle by announcing your exclusivity to the green (and not so green?) world? I meant 'Work with them not 'on or away from them'

I could be wrong in assuming a whole bunch of things. Don't get me wrong! However, I'd appreciate a few responses: from ladies, gentlemen, and managers of the TWIN list. :-D

Come now, sense of humor is required for a manager. Especially tech writing managers.

Your thoughts?

Write to me: Sumank[at]gmail[dot]com

Use it before you write it.

2008-05-02T03:51:00.000-07:00

From the Nikkor ED 80-400mm f/4.5-5.6D VR Review (emphasis is mine):
[quote]Here's the warning in the manual: "When the camera is pointed down, be careful not to hold the lens at the very end as indicated by the black marks in Fig. F, because the zoom ring or focus ring may rotate and pinch your fingers."

Huh? The camera doesn't have to be pointed down for this to happen, so I don't know what Nikon's crack manual writers were on when they wrote that. Worse still, your fingers will often be in that position because this is a heavy lens and you're likely to be trying to balance it by holding it near the front. The first time the camera racks focus on the lens from near focus to infinity at 80mm and your fingers are in the way, you'll get a rude shock as you think your fingers are about to be crushed by the receding front elements (at longer focal lengths, the front elements are further out and pinching is not likely). Fortunately, there's a small ramp on the bezel that tends to push your fingers out of the way, but it's still possible to get seriously pinched, especially if you have fat fingers.[/quote]

OUCH! Very rarely they read what we write and we get caught. So an embarrassed me quickly glances around, ensures no one's watching, and gets off the bus.

Write to me: Sumank[at]gmail[dot]com

The Zoho CRM User Manual

2008-04-24T04:13:00.001-07:00

I admire and respect Zoho a lot. These guys walk their talk on usability. These guys adopted blogging and wikis with a vengeance and I am sure it is paying off.

So, when the cat called curiosity bit me, I downloaded their PDF manual. And, I am sad when I say this, I screamed in my head 'you too Zoho!?' I could see actual content only after 14 pages. That my friend is a sin. And, the bookmarks do not appear on the left-pane. It is bad enough that you offer PDF manuals: you don't zip them; refuse to tell me the size of the file or how long it'd take to download IN TO MY GODDAMNED BROWSER without my permission! Why can't people just zip the PDF! PDF is for print. Not for online consumption.

No, don't say 'everybody does it!' That is not the point. When you as a company set out, embraced, and made usability central to your product(s), why the hell would you treat your user manual like you would a homeless bum?

That said, Zoho's wiki-based documentation seems cool. But PDF... WHY!? gaawd! Why? For a Saas product that too!

Write to me: Sumank[at]gmail[dot]com

My STC India Annual Conference 2007 Slides

2007-10-30T23:28:00.000-07:00

Contingency design does not figure much in conversations amongst technical communicators. In these conversations, the emphasis is usually on the almighty manual. However, oftentimes, customers read error messages before they even think of opening a product's manual. In this presentation, Suman Kumar introduces the key area of contingency design and answers questions like 'How do we design for contingencies?', 'Can you use error messages to boost customer experience and loyalty?', and 'How does effective contingency design help in reducing support costs?'

Find out:
Contingency%20Design.zip (2.28 MB)

Write to me: Sumank[at]gmail[dot]com

I will be talking at the STC Annual Conference in Goa

2007-08-21T01:29:00.000-07:00

Contingency design does not figure much in conversations amongst technical communicators. In these conversations, the emphasis is usually on the almighty manual. However, oftentimes, customers read error messages before they even think of opening a product's manual. In this presentation, Suman Kumar introduces the key area of contingency design and answers questions like 'How do we design for contingencies?', 'Can you use error messages to boost customer experience and loyalty?', and 'How does effective contingency design help in reducing support costs?'

Read more on the STC Website.

Another interesting paper is by Rachna and Shilpa of Cadence: Test plans as a source of improving documentation quality.

Sweet.

Write to me: Sumank[at]gmail[dot]com

Citibank Online Banking: Bad Example

2007-08-01T03:19:00.001-07:00

There's a service called RTGS in Citibank. If you have a Suvidha account and you use the online facility, chances are, you must have seen it on your screen. Now, here's an example that borders on stupidity. The Citibank website says:

RTGS transfers allowed only for amounts between Rs 1,00,000 to Rs 2,00,000
Please do not include spaces or characters. For example, Rs.7,800.00 should be entered as 7800.00

Did you say 'So, what's wrong with that example?' Hmm?

Write to me: Sumank[at]gmail[dot]com

How often...

2007-06-23T04:00:00.000-07:00

...have you clicked OK without reading the message?

Write to me: Sumank[at]gmail[dot]com

Documentation: Google Style

2007-03-03T03:31:00.000-08:00

...now, it is not the video or the technology, but it is the informal tone, that will make users use that document. When will corporations understand this?

Write to me: Sumank[at]gmail[dot]com

Adobe to Release PDF for Industry Standardization

2007-01-29T02:30:00.001-08:00

SAN JOSE, Calif. — Jan. 29, 2007 — Adobe Systems Incorporated (Nasdaq:ADBE) today announced that it intends to release the full Portable Document Format (PDF) 1.7 specification to AIIM, the Enterprise Content Management Association, for the purpose of publication by the International Organization for Standardization (ISO). [Link]

Write to me: Sumank[at]gmail[dot]com

Adobe PDF flaw: more serious than first thought

2007-01-07T22:54:00.000-08:00

A recently discovered security weakness in the widely used Acrobat Reader software could put net users at more risk than previously thought, experts have warned.

Initially, security professionals thought that the problem was restricted and exposed only web-related data or could support phishing scams. Now it has been discovered that miscreants could exploit the problem to access all information on a victim's hard drive, said web security specialists at SPI Dynamics and WhiteHat Security. [read more]

Write to me: Sumank[at]gmail[dot]com

The Science of Word Recognition

2006-11-15T02:36:00.000-08:00

"Evidence from the last 20 years of work in cognitive psychology indicate that we use the letters within a word to recognize a word" [Read more]

STC Annual Conference: I will be presenting a paper

2006-11-14T22:48:00.000-08:00

I will be presenting 'Low Cost Usability Testing' on 9 December at 9:45 AM. Be there.

See the Conference website

Write to me: Sumank[at]gmail[dot]com

Google to Merge Writely and Spreadsheets to Form Google Docs

2006-10-11T02:17:00.000-07:00

Breaking news: Google will announce tomorrow at the Office 2.0 conference a new product called Google Docs, which will merge Writely and Google Spreadsheets into a collaboration and document management solution, according to sources.

The new offering will be available at docs.google.com, although that address produces a 404 error right now. [Read more]

docs.google.com works now.

A technical writer's worst enemy is another technical writer

2006-10-07T00:03:00.000-07:00

Why your coworkers think you are a technical writer with a stick up your a** [Read more]

Use Old Words When Writing for Findability

2006-10-05T03:55:00.000-07:00

"Familiar words spring to mind when users create their search queries.
If your writing favors made-up terms over legacy words, users won't
find your site."
[Read more on Useit.com]

Quality of Communication

2006-09-28T05:19:00.000-07:00

Although technically, e-mail (with or without a hyphen) and its even faster cousins, IM and text messaging, make communicating across time and distance a breeze, it's still the quality of the communication that counts. [via Wired]

Write to me: Sumank[at]gmail[dot]com

Death to Caps Lock

2006-08-17T00:13:00.000-07:00

"The antagonism toward the Caps Lock key extends beyond its misuse by 13-year-old trolls and naive users. Caps Lock is also responsible for failed entries of passwords and other case-sensitive phrases. Users of word processors are forced to retype any text that was entered with Caps Lock accidentally turned on." [via Wired]

Write to me: Sumank[at]gmail[dot]com

A Comma Worth $2.13 Million

2006-08-10T01:50:00.000-07:00

A grammatical blunder may force Rogers Communications Inc. to pay an extra $2.13-million to use utility poles in the Maritimes after the placement of a comma in a contract permitted the deal's cancellation. [Read More]

e-learning 2.0 - how Web technologies are shaping education

2006-08-08T22:14:00.000-07:00

Written by Steve O'Hear and edited by Richard MacManus. This is a two-part series in which Steve will explore how Web technologies are being used in education. Read on!

Technical Writers of India (TWIN) Portal Launch Today!

2006-06-09T23:44:00.000-07:00

Yours truly will be talking at this event. I was responsible for implementing the CMS (Drupal). Be there if this piques your interest.
Start: 2006-06-10 16:00
End: 2006-06-10 18:30
Timezone: Indian
Where: Nahar Heritage, St.Marks Road, Bangalore
When: 10th June (TODAY!) between 4 and 6:30 P.M.

Event sponsor: Interwoven Inc.

Agenda of the event:

a) Welcome - Sandeep Balakrishna (TWIN Admin)

b) Formal launch of the TWIN community/portal - Mr.John Thomas John is the Vice Dean at the Indian Institute of Journalism and New Media. He has 34 years of experience in journalism in India at Deccan Herald, Indian Express, Statesman and Vijay Times, and Reuters, Agence France-Presse and Business Times abroad. His past work has taken him through a variety of roles from sub-editor, reporter, foreign correspondent, news service head, commentary and editorial writer to being a special projects man and media technology evangelist. He has also had brief academic involvement with two other journalism colleges in India, in addition to his recent part-time association with IIJNM. For more information, please check out http://www.iijnm.org/pro-faculty.html#john

c) About the implementation and the CMS, includes a demo of the portal - Pradeep Vasudev and Suman Kumar

d) How TWIN has evolved as a community - a few senior technical writers

e) Recognitions

This event is free for all and entry is purely first-come-first-serve.

Write to me: Sumank[at]gmail[dot]com

One Billion Users and Counting

2005-12-19T21:43:00.000-08:00

Via Useit.com:Somewhere in 2005 the billionth user of the Internet logged on. Jakob says it could be someone from Shanghai. 36% of the Internet users are from Aisa. 24% are from Europe. Only 23% are from North America.
Now, you tell me who should control the Internet? And who actually does?

Technorati tags: web, internet, usability

Write to me: Sumank[at]gmail[dot]com

Documentation in RSS Format

2005-12-02T02:22:00.000-08:00

Here's my idea for leveraging the power of RSS for usable documentation:

Create RSS feeds for documents/manuals and publish it on your support website.

The idea is that users that subscribe to a particular document's RSS feed will know when the document is updated. This is possible because users subscribe to RSS feeds using an ?aggregator (desktop or web-based) that polls sites/web pages to which users had subscribed.

Your users or customers now can access a particular document or chapter without having to visit your site. This, at the outset, may appear counter-productive but studies show that RSS actually increases website traffic. "BBC news site editor Peter Clifton says the site's RSS feeds delivered 26.7 million click-throughs in July, a 30 percent increase over the previous month." (Source: http://www.cyberjournalist.net/news/002835.php )

Customers are notified when a document undergoes a change without the intervention of e-mail.

As against mail-based subscriptions and e-mail newsletters, RSS is ?opt-in? and is free of perils—that plague e-mail—?like spam and viruses. Thus, RSS is a safe, secure, usable way for customers to stay in the know about your products and documentation.

By de-constructing a document into smaller, logical chunks RSS helps customers to access the information they need without having to skim through the whole manual. Most RSS readers allow users to search for content within subscribed feeds, which again offers redundant access to information for customers.
Also, RSS frees content from presentation. Users read RSS content using aggregators or browsers that use their native formatting. I guess most of these readers allow for customization of the format. What's the big deal one may ask; the deal is that users choose how they view your document.

RSS frees your 200-page manual from the clutches of PDF. PDF is not a friendly format for online consumption. And, if your document is a 20MB monster, it will eat up bandwidth and freeze your customer's computing resources. While PDF is excellent for print, it sucks online. HTML is an alternative, but it lacks the pinging/notification features of RSS and is a spoilt brat thanks to competing browsers and lack of rigid standards until recently. RSS standsout as a fluid yet robust alternative to boost your document's usability. It is gaining wide acceptance as we speak, and is fast losing its complexity. Gasp! Please bear with the verbosity guys!

Firefox supports RSS auto-discovery and subscription features (the orange icon at ~~bottom-right~~ the right in the address bar).

Internet Explorer 7 will have RSS support built-in. See related entry on MSDN: http://blogs.msdn.com/ie/archive/2005/08/02/446280.aspx

RSS allows customers easy access to specific sections of a document and by boosting the readability of documents (because information is chunked in RSS) it encourages users to use documentation to solve issues rather than call or e-mail your support team. Thus RSS is one of the most significant ways to cut-down support costs and improve customer satisfaction.

Last, but most important, generating RSS versions of your documentation will not involve any major extra effort. If you already use XML to create documentation (via structured Framemaker or other tools), you just have to modify your XSLT to generate another output in RSS format.

What do you guys think? Have your tried it in your work? If yes, please share your thoughts.

Technorati tags: RSS, documentation, technical writing, communication

10 Ways to Please Us, the Customers

2005-11-10T00:02:00.000-08:00

NYT published this list. I thought the ones below might ring a bell to all you tech writers out there:

II. Thou shalt hire native English speakers to translate thine instruction manual. "When the camera focus is not so possible, hold the shutter button vaguely until the beeping tone is heard." Is that really how your company wants to address customers?
Talk about New Math. You'll spend millions of dollars developing some breakthrough gizmo, but won't spring for somebody to rewrite your manual in proper English? I know some high schoolers who'd do the job for $50 and 10 free ring tones.

VI. Thou shalt not hide from thy customers. If you've designed your product properly and provided a decent manual in English, you ought to have nothing to hide; there should be very little reason to worry that we, the masses, will jam your phone lines asking for help.

Thanks King!

Engrish!

2005-10-09T23:50:00.000-07:00

MS Office 12 to Support PDF

2005-10-05T04:42:00.000-07:00

Microsoft has announced that it will introduce PDF (Portable Document Format) support in its forthcoming version of Office, code-named "Office 12", scheduled for release in the second half of 2006.

Reportedly, the PDF format will be integrated in MS Word, Excel, Publisher, PowerPoint and InfoPath among other applications. Microsoft maintains that the inclusion of PDF in Office 12, will further broaden the appeal of the program.

Microsoft says that it is adding the "save to PDF" feature, with a view towards satisfying users who want to share documents with people, including those who don't have MS Office.
Read more on TechTree

Aah?

2005-09-09T01:50:00.000-07:00

The other day a couple of my colleagues were discussing about the bad habit of adding the ‘aah’ sound while phrasing a question. I don’t know if it is bad; but it sure will give ulcers to the purists.
Take for example how ‘are you coming with us?’ is brutally hacked to a single word question: coming-aah?
Or, the totally new form of exclamation: ‘Yes-aaah?’ that roughly translates to ‘don’t tell me it is true!’
Or the usual friendly enquiry ‘you ate-aah?’ that is the equivalent of ‘did you have your lunch?’
The ‘aah’ sound is widely used—especially in interrogative phrases— in Tamil and Telugu:
‘Saapteengalaah?’ (Did you eat? - Tamil)
‘Varreengalaah?’ (Are you going with us? – Tamil)
‘Baavunnaaraah?’ (How are you? – Telugu)
‘Bon-chesaraah?’ (Have you eaten? – Telugu)

And we south Indians use the same construction even while conversing in English. I think it is a unique fusion of two different linguistic rhythms. The purists may scoff at it, but I enjoy using it and listening to others use it.
You like it-aah?

Tech writer or DTP Expert?

2005-09-05T04:15:00.000-07:00

I saw these requirements for a technical writer opening on one of those ‘Urgent-wanted tech writers’ mails:

HTML programming, Javascript
Microsoft Office suite (Word, PowerPoint, Excel), Microsoft FrontPage
Macromedia Dreamweaver
Macromedia Flash
Adobe Photoshop, Adobe ImageReady, Adobe PageMaker, Adobe Acrobat,
RoboHelp
Microsoft Visio

I wonder why they left out C, C++, Java, and VisualBasic? Why, why? When will they learn to tell a writer from a DTP professional? What has Flash got to do with a tech writer’s job? Javascript for heaven’s sake!

A brand name gone wrong

2005-08-18T23:12:00.000-07:00

"Did you know that Heroin was originally a brand name for cough syrup? In 1874, German scientists developed a formula for a painkiller that they thought would be less addictive than morphine. They simply added two acetyls to morphine to synthesize diacetylmorphine.
Heinrich Dreser, the head of Bayer drug development tried it on animals and humans. He, also, tried it on himself, which may have been the problem. He was very pleased with the results and decided it was a good treatment for many ailments especially respiratory ones like bronchitis, asthma and tuberculosis." Read more on Free Enterprise Land

Interactive Documentation

2005-08-03T03:03:00.000-07:00

Novell has a 'Comments' feature on its product documentation pages. User can leave their feedback instantly, instead of sending an E-mail later. (But why does the RSS link fail on your site guys?)

Microsoft too has an instant feedback feature for its documentation, but somehow I don't like it. It appears to be complex, as compared to Novell's.
But I like PHP.net's interactivity the best. Don't ask me why. It is just subjective I guess.

Anyway, out of curiosity I went to Apple's iPod site (I own a Shuffle) and I discovered to my utter dismay the terrible feedback mechanism they have. Gray text on gray background and they expect users to notice that 'Provide Feedback' link. Ambitious. I expected something better from Apple.

Review of Screen Capture Tools

2005-08-01T21:40:00.000-07:00

Check out the Review of Screen Capture Tools. Neat.
[Via Usable Help]

Microsoft goes the RSS way

2005-06-07T04:31:00.000-07:00

The Microsoft Help and Support site is now providing an RSS feed (Really Simple Syndication) for its Knowledge Base (KB) articles. [Link]

Well, well, well. MS is only syndicating its KB articles, but I am thinking a step ahead: deliver a user manual (also) through RSS. Most organizations are moving (or have moved already) to XML based authoring, and generating RSS feeds from there should be a walk in the park.

Aside: What would happen if online manuals had a 'Comments' feature like in our blogs? Chew on it.

To Click or Select...

2005-06-06T02:20:00.000-07:00

Your styleguide says it is 'select'. The whole world says 'click'. You are confused. So am I. I have tried being informal while writing instructions: "Hit the Submit button to complete regiustration." But they spanked me for being so casual and changed 'hit' to 'select'. You know, no one reads manuals. Now I know why.

Need inputs: Talk on usability

2005-05-11T23:55:00.000-07:00

Hi folks, I have been invited to talk about usability to a bunch of people that are training to be technical communicators. The duration of the session is two hours. I don't want it to be a 'words only' session. Of course, I would be talking to them about the basics, the importance of usability, standards, product design and usability, and user-centered design. What I am thinking about is some kind of an exercise, a practical session, for the participants. I was thinking if I should ask them to run a quick UI review on their mobile phones (and take it from there... UI standards for mobiles, gloss vs. Utility etc.).
If you have any comments suggestions, please leave a comment.

Prepend

2005-04-20T02:16:00.000-07:00

Came across this term Prepend. Prepend is a word commonly used as the antonym of append, which means add at the end. Prepend is not a valid English term. But I don't think it will stay that way for long.

GUI Glossary

2005-04-14T02:54:00.000-07:00

Checkbox or check box? How many times have you been caught in that awful knot? Here is a little help:
GUI Glossary: definitions of frequently used GUI terms.
Enjoy!

Enhancing Internal Communications with Blogs, Wikis, and More

2005-02-09T21:03:00.000-08:00

Insightful presentations by Nick Finck, Mary Hodder, and Biz Stone. If you are in anyway related to Intranets you may want to check these out:
Enhancing Internal Communications with Blogs, Wikis, and More

The Why and How of Blogging

Merry Christmas Folks!

2004-12-24T03:20:00.000-08:00

Merry Christmas Folks! Have a great holiday season and a terrific new year. :-)

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

Comments System: Anyone Can Post Comments Now!

2004-12-23T23:34:00.000-08:00

Folks, I know some of you were irritated by the fact that you had to login (if you're a Blogger user) or post as Anonymous while posting comments on this blog. I have done away with that. Now, anyone can post comments. No need to login to Blogger and stuff. Trust this improves the interaction here. I should have done it long time back (when Guy Haas suggested it) but I did not... Well, it is never too late. Give it a spin and offer feedback! And hey, Merry Christmas!

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

Hollywood May Hire You!

2004-12-20T21:21:00.000-08:00

Check this out. This is a brilliant observation:
>"Screenwriting = Creative Technical Writing"

Firefox: Tech writer friendly!

2004-12-09T00:24:00.000-08:00

Firefox has an in-built popup blocker.

Firefox saves your screenspace through its tabbed-browsing feature. Firefox allows for opening multiple sites using tabs (within
one instance), unlike IE that opens a separate instance of the browser everytime you open a new window. What it means is that you could be browsing 20 sites, but there is only one Firefox window. Very cool.

Firefox allows you to highlight your search results. When you are searching for a keyword on a webpage (ctrl+f) you can set Firefox to highlight the matches.

FireFox Allows you to search dictionary.com (without having to visit dictionary.com).

Firefox is RSS friendly. It auto-detects RSS feeds from any website and allows you to bookmark it as a 'live bookmark'. Refresh the bookmark to see what's latest (through a drop-down).

Firefox allows you to select text from a web page using your keyboard! Yes, you can scroll through the page using the arrow keys. Hit F7 on your Firefox and check it out.

And, migrating to Firefox is a breeze. Firefox imports your existing settings from Internet Explorer. An import wizard will run when you first install Firefox (and is also available later through the File menu, File > Import), and it imports your Favorites, options, cookies, stored passwords, and a variety of other data. This saves you time customizing Firefox to fit your needs.
Also, the United States Computer Emergency Readiness Team (US-CERT), a division of the Department of Homeland Security, recommends switching from IE to an alternative browser, thanks to certain severe security exploits in IE.
So, what are you waiting for? Download Firefox now!

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

Tech-writers – A Necessary Evil

2004-11-15T23:24:00.000-08:00

In a world where accuracy is all important, a lot goes over the head of the dummy. I don't know if it's intellectual snobbery, but programmers and managers seem to think that if they understand it, so should the user. It doesn't matter whether or not they do… they SHOULD! Stupid users! Maybe it's the geek's ultimate revenge…

Your document can be 100% accurate, but if the audience can't read it, you've wasted your time.

Excerpt from Glenn Murray's article - Tech-writers – A Necessary Evil (via WebproNews)

I told you! Didn't I?

Wipro blogs!

2004-10-31T06:16:00.000-08:00

Wipro Technologies is probably the first IT organization in India to embrace blogging. They have started http://wiproweblog.com. I was surprised when I found a link to their blog site on their home page. Very cool.

Switching careers: Madman's story of making a business out of one's passion

2004-10-23T02:22:00.000-07:00

Folks Madhu 'Madman' Menon is is featured in an article on career-switching in The Hindu..
When the great exodus to the IT industry started, just about everyone dropped what they were doing and flung themselves into the gold rush; some wanted to move to the USA, some wanted to make money, and some wanted both. From the early 90s to now, things have changed. Last year not many engineering entrants were interested in taking up IT as a branch of study. The honeymoon, sadly, is over. But amid this mileu a few individuals had the courage, initiative, and the brains to break into entrepreneurship. Madhu 'Madman' Menon is one of them. I am not surprised that The Hindu featured him in this article:
The Hindu Business Line : Doing business with relish

There's a lesson in it for each one of us. IT is not the only pasture. If only you applied your brains, you could hit upon a great idea. India needs entrepreneurs.

Madhu, make it two. ;-)

Off shoring of Documentation: a survey

2004-10-07T02:28:00.000-07:00

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

Writing SI units and symbols

2004-09-21T02:14:00.000-07:00

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:

The short forms for SI units (such as mm for millimeter) are called symbols, not abbreviations.
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.
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.
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
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".
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

Travails of a tech writer

2004-09-15T21:33:00.000-07:00

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

Finding the voice

2004-09-13T04:18:00.000-07:00

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

Oxford Plain English Guidelines

2004-08-26T04:55:00.000-07:00

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

FAQ from Gregg Reference Manual

2004-08-25T23:23:00.000-07:00

Questions and suggestions from users of The Gregg Reference Manual

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

Wanted: Sr Technical Writer for Informatica Corporation

2004-07-30T03:04:00.000-07:00

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

Style guides: Sacrosanct?

2004-07-28T02:13:00.000-07:00

How many times have you paused and reflected, ‘man, I know I am right, but the style guide does not agree…’?

For example, some style guides proscribe the use of the possessive ~~pronoun~~ noun (earlier I had written 'pronoun'. Thanks Guy for pointing it out.) and demand that you elaborate: IP address of the Server as against Server’s IP address . In certain contexts I prefer the latter; for it is shorter and I am sure it won’t confuse the users. But the style guide does not agree.

I think that a style guide is by no means sacrosanct. It is around to help us, and not to put us in dilemmas. So, if you strongly believe that certain rules of the guide are rigid do share your opinion. A style guide evolves. It needs inputs from all concerned for it to become comprehensive, robust, and current. Do we need styled guides at all? Yes sir, product documentation needs to be consistent in terms of tone, style, and grammar. So, we need style guides. Also, when there is a team of writers working on the various modules of the product, a style guide helps in making the documentation coherent and consistent.
You thoughts?
Some style guides...
The American Psychological Association (APA) Style

Columbia guide to online writing

Lynch Guide

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

Wanted: Technical Writers for Wipro Technologies, Pune

2004-07-19T23:44:00.000-07:00

Wipro Pune is looking Technical Writers with three plus years of relevant experience.
If you

have worked on creation of user manuals, installation guides, FAQs, and glossary

Possess an incisive perspective of the technical writing process

Are well versed in publishing tools like Framemaker, Dreamweaver, MS-Office, and Webworks

Send your updated resumes to suman@sumankumar.com

Job location: Pune
Number of vacancies: four

Rush your resume now!

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

Job openings for young under-grads and graduates in Spectramind

2004-07-09T05:15:00.000-07:00

Spectramind the BPO arm of Wipro is looking for Under Graduates/Graduates with Knowledge in Operating Systems, Email Support, Trouble shooting in Connectivity Problem, Windows 2000, XP, 9X.Microsoft Internet Explorer, Networking Management, Working knowledge of Microsoft® Windows NT® Server and Windows 2000 Server, Working Knowledge of Exchange or comparable e-mail system TCPIP, Hands on in Switches, Routers & LAN / WAN, DOS and PC technology and applications.
Rush your resume to one of the following e-mail ids based on your location preference.

Rush your resumes to one of the following e-mail ids

New Mumbai - wsmcareersbelapur@wipro.com

Chennai - wsmcareerschennai@wipro.com

Delhi - wsmcareersdelhi@wipro.com

Powai - wsmcareerspowai@wipro.com

Pune - wsmcareerspune@wipro.com
Please refer my name (Sumankumar.R) and e-mail id [kumar.suman (at) wipro (dot) com]in your e-mail

Installing a gas stove: Why I think technical writers are important to this green earth

2004-07-08T04:59:00.000-07:00

This morning my wife woke me up from my dreams of swimming with the Dolphins in Mauritius and hollered, 'get the gas stove working man!'. Groggy eyed, I went to the kitchen and unpacked the stove. The burners kept falling off and there were no instructions on the stove or the packaging about how to fit the burners and the knobs. That was the easiest part, you can bring your eyebrows down.
So, I pulled the new gas cylinder that weighed a ton. I had to fix a regulator to the cylinder. A closer look revealed a seal on the mouth of the cylinder. I glanced at my wife who was watching my progress. 'Pull the seal off honey!', she purred, as if it was something even Bush would have figured out. I mumbled an incoherent retort and started pulling the strong wire that bound the cylinder and the seal. I pulled hard. No luck, the damn thing wont budge. I squatted and peered on the walls of the cylinder to find some information that would help me. Nope! No such luck. So, I pulled harder. And the wire cut my left-thumb. My left palm was all crimson. I was incensed. What kind of a manufacturer would ship some thing like a cooking gas cylinder without an installation manual? Bharat gas. Ah!

I squatted again and this I noticed an arrow mark on the seal. Out of curiosity I pulled the wire parallel to the ground (I was pulling it 'up' earlier) and the seal slipped off the cylinder's mouth. Neat! But hey, you know, I would have liked it better if some one had stuck a sticker or probably given a single-page manual on how to install the regulator. If you thought my troubles are over. Think again.

Overjoyed with the seal coming off the cylinder I pounced on the regulator and -you guessed it right - blinked. I rolled it around to find some directon, some snippet that could get me started. My wife started admiring the ceiling, suppressing her laughter. But dude that I am, I was least offended. I took the regulator and started jamming it on to the mouth of the cylinder. Nope. Things are never that easy. I tried everything from banging the regulator's head to dropping it off from a height on to the mouth of the cylinder. Nothing worked. It would just not sit and settle down in the mouth. Frustrated I was pulling up the regulator, and I discovered the slide lock around the regulator. Slide up the lock, sit the damn thing on the mouth, and let go! The regulator squatted firm on the mouth, like a drunk on a barstool. Simple, yes, but... Yeah, yeah if only some one has written it some where.
Now, if you thought my troubles were over. Think thrice. The cylinder supplies the stove with the gas using a reinforced rubber and steel hose. I had to fix the pipe on to the tiny nozzles of the stove and the regulator. And I managed to do it using sheer force. And lost more blood from the cut on my thumb. It is absolutely impossible for a housewife to do it.

As my wife made coffee on our new stove, I was thinking: We technical writers are an important link between products and users. We guide and direct a product's use. A rocket engineer might design a rocket, but who tells the astronauts how to use the loo or the inter-galactic phone in the darn rocket? You.

So, my technical writing friend, the world would be a miserable place without writers like us. Don't go on that cloud number nine yet. Relax. Come down here and listen to daddy: Please remember this poor guy that cut his hand while pulling off the seal from the gas cylinder. If you had had written that small note ('Pull gently, parallel to the ground.') he wouldn't have a cut his thumb today. Remember a product's use overrides the product itself. No use. No product. No user. No use. Follow this and you will be able to afford those cruise trips, and yes, Dolphin watching in Mauritius.

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

Context Sensitive 'Sticky Notes': Stick a Sticky Note to your Blog!

2004-06-17T04:03:00.000-07:00

Conceptworld's Quick Notes Plus might appear like any other Sticky Notes Plus (QNP) program, but its context-sensitive notes feature is mind blowing: QNP is the closest to our paper sticky notes. What I mean is you can stick a paper note anywhere you want and that's what makes them useful. Say, your TV needs repair. You just stick on note on it saying 'Take me to the mechanic or call the mechanic' and every time you drown your lazy butt in the couch the note on the TV reminds you that you have to fix the TV. Paper Sticky Notes are naturally context-sensitive. Most Virtual Sticky Notes software are not. That's where QNP scores. And I think its context-sensitivity alone will make it a leader in its market. So, good luck QNP.
Other possible uses of context-sensitive notes by QNP:

Stick a Note to your weblog: 'need to write about the Paris trip' and every time you open your weblog the note would remind you that you got to make a post about your trip. This is cool or what?

Stick a note to any document (finished, unfinished)

Stick a note to Winamp! (download reminder?)

Stick a note to your e-mail program (Outlook or Notes or Eudora). Though most e-mail programs have notes in built; the notes are not prominent... QNP notes appear when you open the e-mail program... and appear prominent.

Stick notes to your Yahoo Messenger 'remind John about the party'!

I can go on but I know you got the drift. So why don't you
visit QNP's site and give it a spin? And hey QNP's priced version is only $24.95 and that my friend is a steal.

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

New resources for tech writers in India

2004-06-15T09:49:00.000-07:00

People I have added a 'Classifieds' program to this site. It is in beta. I am just testing it. Give it a spin at Job Ads and also see The Job Forum.
Tell me which one you like the best. If you have other ideas please let me know. Pass it on to your tech writer friends too.

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

You are Invited

2004-06-08T07:34:00.000-07:00

After a marathon long-distance courtship of four and a half years, Chitra and I are tying the knot. Be there to share the moment, wish us luck, and see us off as we take our first step towards a journey of a life time.
"When? Where? Whaat?" -> More information here. So all ye blogger friends: be there.
Write to me: suman 'at' techwritersindia 'dot' com

Opportunity: Tech writer for developing dictionary of terms

2004-05-20T04:46:00.000-07:00

Tore Nestenius is looking for a good tenchical writer who can help write a kind of dictionary for software development terms and computer hardware terms. Where terms/words are explained. Interested? Rush your mail to synchron(at)algonet(dot)se .

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

WebWorks Publisher 2003 - An introduction

2004-04-12T03:14:00.000-07:00

WebWorks® Publisher is not a Help authoring tool in the traditional sense. It is, rather, a tool for converting documents created in Microsoft® Word (2000 or XP) or Adobe® FrameMaker® (5.5.6 or later) to any of 11 different online output formats, including 5 different flavors of online Help.
More on WritersUA (formerly WinWriters)

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

Microsoft Longhorn Help: Highlights

2004-04-12T03:12:00.000-07:00

"Authors will develop content for "Longhorn" Help using an XML-based markup language called Microsoft Assistance Markup Language (MAML, pronounced "mammal"). Unlike HTML, this markup language is presentation-independent: topics and the elements they contain are defined semantically. For example, in HTML it's common practice to format menu options and other user interface elements with a bold tag. In MAML, you would instead apply the <ui> element to identify the purpose of the text. MAML consists of a number of distinct content types, each of which defines its own set of valid constituent elements. Examples of content types include conceptual, FAQ, glossary, procedural, troubleshooting, and tutorial." Read more: WritersUA - Microsoft "Longhorn" Help Highlights

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

Technical Writing Glossary

2004-04-12T03:10:00.000-07:00

I think this is a neat idea and is an excellent resource for aspirants and practising pros alike. Check it out.
http://members.iinet.net.au/~mbuckler/glossary1.shtml
write to me: Suman[at]sumankumar[dot]com

Participative Help Design

2004-04-05T11:08:00.000-07:00

Participative Help Design

I used a weblog script to create online help for -uh- using weblogs. I used a plugin to pull help topics as alphabetical links. The script has in-built search. So, there, I had an index and a search. And I left the 'Comments' feature alone. And guess what, I had users commenting on individual topics, which resulted in fine tuning the help and making it user-centered.
So, I conclude that user-feedback even after the documentation is released is invaluable and is much more relevant; users give feedback based on how they use the Help system. I'd say it is a nice way to fill gaps that you may have overseen during your project. I am talking from experience!
I used Nucleus: http://nucleuscms.org. People ask me why not MovableType; simple, it is not open-source like Nucleus. So, experiment with blogs and tell me if you can, how it helped you.
write to me: Suman@sumankumar.com

3rd STC Chennai Meet this sunday.

2004-04-02T01:50:00.000-08:00

3rd STC Chennai Knowledge Sharing Session this sunday, April 4th.

This month's knowledge sharing session will be held this coming sunday, april 4th at Cognizant's office at 10:00 a.m. Please do spread the word around.

Day & Date : Sunday, April 4, 2004
Time : 10 to 11 a.m
Venue : Cognizant Technology Services (CTS), 3rd Floor, Conference Room, Whites Road, Royapettah.
Contact Person : Kiruba Shankar . phone : 52133619 (res) , 52150505 (off)
RSVP : kiruba @ kiruba.com
Door Charge : Rs.20 ( Snacks will be served )

We are planning to get a video camera along so we can record the presentations and discussions.

Localization and Internationalization

2004-03-16T15:30:00.000-08:00

Localization and Internationalization

Internationalization: Writing in a neutral, simple language so that the document can be translated to other languages without much trouble. There are standards for it like the The European Association of Aerospace Industries (AECMA) Simplified English. The AECMA Simplified English (SE) dictionary is defined in the AECMA standard PSC-85-16598 developed by the aerospace industry.

Localization: The actual process of translation.

At least, that's what I have understood.

Now you know why you have to keep it simple when you write that manual, don't you?

Important note: Robohelp gives a lot of trouble in translations. That's what I have heard at least.

write to me: Suman@sumankumar.com

In Denver

2004-03-08T07:24:00.000-08:00

Guys I am in Denver. So updates will be erratic. I should be back in India around 18th of March. Until then, bye!
Suman
write to me: Suman@sumankumar.com

2004-02-24T16:31:00.000-08:00

Next STC Chennai Meeting On March 7 : This will be the second knowledge sharing session. The first meeting was a wonderful success and we hope the second one will be even better. Take a note of the details..
Day & Date : Sunday, March 7, 2004
Time : 10 to 11 a.m
Venue : Cognizant Technology Services (CTS), 3rd Floor, Conference Room, Whites Road, Royapettah.
Contact Person : Kiruba Shankar . phone : 52133619 (res)
RSVP : kiruba @ kiruba.com
The theme of the meet is "Bring a tech writing friend".

2004-01-27T21:28:00.000-08:00

I am engaged

I got engaged to Chitra on 25 Jan 2004. I was busy traveling and making arrangements. The other news is that I have published my first novel; visit http://sunnu.blogspot.com to read 10 free chapters. If you like what you read go right ahead and buy the novel at http://cafeshops.com/sunnu.
I will resume posting on this blog tomorrow; let me find a nice topic. Thanks people.
write to me: Suman@sumankumar.com

2004-01-16T00:12:00.000-08:00

Chennai Tech Writers Mixer on Jan 25 : Calling all Tech Writers in Chennai for an informal Mixer on Jan 25th. It's a great opportunity to network with our fellow tech writers from different companies in Chennai.

The Mixer aims to be a nice watering hole for chennai tech writers to meet up and share their experiences and knowledge in an informal atmosphere.

Here are the things to remember.
Day & Date : Sunday, Jan 25th 2004.
Time : 4:30 p.m
Venue : Amethyst cafe. ( It's a really cool place to hang out )
Bill : We just go dutch on the snacks and drinks.
Directions : Take the lane next to Hotel Saravana Bhavan on Peter's Road, Royapettah. Go down the lane for about 100 meters and you'll find Amethyst on the right.
Contact : You can mail Kiruba Shankar at Kiruba @ Kiruba.com or call his residence at 52133619 after 7:00 p.m

Please do spread the work to your tech writing friends in Chennai. Thanks in advance.

2003-12-20T22:47:00.000-08:00

Usability Testing of Your Documentation

Yea, it is possible. Let's say you have created a user-guide. The user-guide is aimed at helping users in performing various tasks on the product.

Choose a representative user (anyone, even your mother-in-law is all right). If you can't recruit a user read List-item:

Ask the user to perform tasks on the product using the instructions from the guide

Ask the user to Think Aloud, but don't interrupt or help the user in performing tasks

Make notes. Note the reactions of the user. That frown. That click of the tongue indicating frustration. People are nice; they wont tell you to your face 'Your guide sucks.' It is our duty to find out what they think

Make a list of your findings; identify action points; compile a report, and go to work on the guide

Once you have incorporated changes/enhancements to your guide, test it again on the user and make sure that your enhancements have made the guide usable

If you can't recruit users, you and your other technical writer can review the guide (individually) against a heuristics check-list. The check-list is intended for a software application but you can use it for your guide as well, if you know what to keep and what to throw away (discretion my lord!)

Disclaimer: If you thought this idea of testing is stupid, please tell me, I am just thinking aloud and sharing the thought with you; maybe you and I can discover a method that would be world renowned, who knows!

write to me: Suman@sumankumar.com

2003-12-05T03:41:00.000-08:00

Microsoft LongHorn Help

The next generation of the Microsoft Windows operating system, codename "Longhorn", promises to raise the standard for performance and innovation. The Windows "Longhorn" Help system is designed to greatly improve the user assistance experience in Windows.
"Longhorn" Help includes the following features:

A new structured authoring model enables Help authors to create higher quality Help content, leveraging the flexibility of XML.

A unified Help viewer pane, which is shared by all applications, provides a consistent entry point to Help.
A new organizational structure based on common tasks, rather than application features, makes it easier for users to find the Help they need.

Active content displays the most appropriate Help content, based on the current state of the user's computer.
A more efficient update model continuously provides connected users with the newest content; each update contains only updated material, which conserves bandwidth.

Links:

Longhorn page on MSDN
About Microsoft Assistance Markup Language (MAML)

Note: Learn XML buddy; that's where the future is. In probably a couple of years organizations will start mentioning this in their recruitment ads for tech writers: "Help authoring skills using 'Longhorn' (or whatever the actual name is; Longhorn is just a code-name)"
Tools Die. Concepts don't. Get it?

write to me: Suman@sumankumar.com

2003-11-24T03:47:00.000-08:00

How to become a technical writer

I got a few mails from aspiring tech writers asking how to be a technical writer. I'll assume that you guys are asking me 'how to get a technical writer's job'. Please note that the content below is inspired by what little I know; don’t go by it word for word: get the idea and work your own path. Good luck!

All writers are not technical writers

Technical writers spend their time a) Researching (on a product) b) Collecting information d) writing and d) designing/Publishing. There could be more, but most tech writers do all of the above. So get the hint: we 'also' write. So being a writer doesn't mean you can easily become a technical writer. You need (according to me):

Patience to research
A knack for collecting information from various sources
The skill to write in simple English. Write less, say more if you will
Excellent inter-personal skills: you'll be interacting with technicians, users and managers, and trust me, it is not easy (especially the technicians :-) )
A passion for learning new stuff; you should be the kind of person that wonders 'how does this CDMA phone work?' 'How does this text-through e-mail- reach someone in USA within seconds?' 'How do they make glow-in-the-dark panties?' And so on. You have to be a curious person that always wonders how stuff works.

If you asked me 'okay I got all that you mentioned above, will i get a job?' My answer is 'I only look like god.' ;-)

Tools

Publishing skills are crucial for a technical writers repertoire. So you got to be acquainted with all the widely used desktop/web publishing tools like Adobe FrameMaker, Robo-help. You need to know HTML. So much of documentation is being delivered online so knowledge of HTML is -at least to me- a very basic skill that you need to acquire.
FrameMaker and RoboHelp are popular today, this might change. Tools change. Concepts don’t. The point is, your being an expert desktop publishing technician doesn’t mean that you are a technical writer. It is like saying ‘all English professors are writers.’

Cracking that job

Cracking a job is an art, and a science. Decide first who you want to work with. Let's say you want to work with Intel; study about your target. What is the company into; do they have offices in your town? Go through their documentation (most product companies offer it online) and get a feeler of what these guys are about. Prepare an effective resume. Find the e-mail id of the target company's recruitment exec or just call them up and speak to the front office and ASK (we don’t often) who is the documentation manager? Send your profile across. Do the above a 100 times (I mean to 100 companies genius). Normal hit rate is 10% given there aren't any over riding factors like your country's been hit by a nuclear bomb or the industry is at its worst ever low in 1000 years... if all is normal you should get a call. After that it is your confidence that'll win you the job. But as I said focus is important. You should know what you want and most important: what you don’t want. Let’s sum it up:

Freeze on target company
Study target
Identify contacts
Tweak/build resume
Write a nice covering letter
Mail it to them

If you are wondering ‘how am I going to research about a company?’ well, find another career option buddy. Ever heard of google?

Using job sites

A site like naukri.com is a boon to you. It cuts your work by about 70%. So register your resume there. Choose the right keywords; employers search for profiles with the keywords. You can visit the site periodically and search for 'technical writers'; you have the option of narrowing your search to a particular city. Now, isn't that wonderful?

Certifications

Get brainbench certified in written English. According to me there is not a single school in India that offers courses on technical writing. So if you got the money you can go to USA and study there. I was of the opinion that certifications don’t matter much, but they are proof that you are competent.

Conclusion

There are no easy ways to success. There are no ‘become a technical writer in 30 days’ programs. You are on your own and your chances are as good as you are. My only advice is that use the Internet to learn more.
Let’s start with an exercise. Find out the information about topics given below and put your findings in comments:
1) Biography of Roald Dahl
2) What is royal jelly?
3) What is cryogenics?
4) Who wrote The Purloined Letter? What is the story about?

Let’s see if you got the knack to collect information!

2003-11-14T01:51:00.000-08:00

Escape From the Grammar Trap

by Jean Hollis Weber
Too many editors focus on the details and don't pay enough attention to the bigger picture. Editors can--and should--add even more value through substantive, technical, and usability editing.
(...via TECHWR-L)
write to me: Suman@sumankumar.com

2003-11-11T06:06:00.000-08:00

Help: How helpful is it?

I read on Usable Help:
"According to the 2002 National Assessment of Adult Literacy, about 50% of the US adults studied demonstrate literacy skills at Type 1 or Type 2 levels. This means that respondents are, at best:
"[A]pt to experience considerable difficulty in performing tasks that required them to integrate or synthesize information from complex or lengthy texts or to perform quantitative tasks that involved two or more sequential operations and in which the individual had to set up the problem."

Gordon said even if you wrote in simple sentences the basic DNA of help, text and sequential steps make it difficult for adults to use help.
Me thinks that a combination of graphic content (video, flash) and succint text (where it is needed) can help.
Glossword offers an alternative version of help: Video Help - just watch and do! But this is not feasible for bigger projects.
update 14 November 2003
Viewlets probably are a solution to ensure your users understand and act; but you see most of it depends on who your user is. For a geek a text file would do. For a normal user you may consider html or pdf. For people of Type 1 and Type 2 you may want to look at Viewlets. Qarbon, manufaturers of Viewlet builders claim:

"ViewletBuilder's innovative content creation process has revolutionized the way in which software is presented and demonstrated. The history of online demos can quite literally be divided into a pre-Viewlet era and the post-Viewlet era. Before ViewletBuilder introduced its ground-breaking screen-capture animation process to the world in 1998, application demos tended to be lengthy “movie” files, which were difficult to edit and virtually impossible to update. Today, ViewletBuilder's patented content creation mechanism allows users to take a series of completely editable screen captures that are then animated to produce a flawless Flash simulation."

But I would rather wait and watch. the very fact that it involves Flash makes me wary. What if some of my users don't have flash plugins in their browsers? And I was testing the viewlet demos on qadron's site; I am not too happy with the time each Viewlet took to download. So, That's that.
Note: Glossword is an amazing open-source tool that enables collaborative dictionary/glossary building; it is a browser based product. You should give it a spin; I found it to be of great help.

write to me: Suman@sumankumar.com

2003-10-15T06:41:00.000-07:00

Character Sets: What are they?

Unicode and Character Sets: Thanks Joel!
(It looks like Joel's taking up too much space on this blog... hmm?)
write to me: Suman@sumankumar.com

2003-09-18T01:32:00.000-07:00

Joel on Software - The Guerrilla Guide to Interviewing

How to weed out the 'unwashed masses'? How to discover and hire the brilliant superstars? Read on:
Joel on Software - The Guerrilla Guide to Interviewing

2003-09-16T04:27:00.000-07:00

The Best e-Learning Sites Links from e-LearningGuru.com

2003-09-08T22:21:00.000-07:00

Blogging and Security

Scott Granneman writes on securityfocus.com about how blogs can be a security pro's best friend.
SecurityFocus BASICS Columnists: Blogs: Another Tool in the Security Pro's Tool

Re: [twin] Course Content for Technical Writing

2003-08-19T11:56:00.000-07:00

Hi
Your hard skills are okay. But you are not specific when you say 'team
skills' I mean today everyone is expected to be a team player so it is not
necessarily a skill you know? I'd rather focus on specific skills
like 'interviewing skills' and 'survey skills': a tech writer spends lot of
time interviewing subject matter experts and technicians to collect
information.
And on the technical front I strongly recommend they understand and learn
SGML, XML, HTML (stuff like the docbook DTDs is important). They have to
understand Mark up languages in order to write something that can be
published anywhere (cross platform). You may want to add in tools like
robohelp, framemaker PLUS a basic course on 'help' formats (winhelp, java
help, htmlhelp and so on).
A technical writer writes to an audience so her work has to be user-friendly
so you may want to include a primer on usability and usability testing. (I
can provide material on this)
I think a good technical writer is one that is not afraid of code, that is
ready to skim through reams of material, one that loves talking to people,
one that knows the rules of the language and knows when to break them. And
finally one that loves to write. And understand what 'being objective' is.

Hamsila wrote:
>
>Hi All
>
>I have been asked to help develop a post graduate diploma in Technical
>writing. This could possibly train novices in the field or those wishing to
>take up Technical writing as a career.
>
>As I see it, there are two sets of skills required:
>Hard Skills:
> Language
> Tools
> Editing
> Proofreading
>
>Soft Skills:
> Interpersonal skills
> Team skills
> Research skills
> Motivational skills
>
>Is there anything else that could be included?
>
>Regards
>Hamsila
>
>
>
>..........................000000000000................................
>Send messages to: twin@user.itconsult.co.uk
>
>Leave TWIN: Send blank email to twin-leave@user.itconsult.co.uk
>Join TWIN: Send blank email to twin-join@user.itconsult.co.uk
>Digest Mode: Send blank email to twin-digest@user.itconsult.co.uk
>
>Post Job-Ads: Send job-ad to: twinjobs@user.itconsult.co.uk
>
>List Owner: twin-owner@user.itconsult.co.uk
>TWIN Website: http://www.twin-india.org
>TWIN Archive: http://user.itconsult.co.uk/twin/archive/
>
>
>

2003-08-18T05:49:00.000-07:00

Latin Words Used in The English Language

Trust me, you’d feel like an oaf when someone rattles out a Latin phrase like ‘Sine Qua Non’ or ‘Summa Cum Laude’ and it goes over your head. You just grin, not indicating whether you understood the damn phrase or not. That’s definitely not the position I want you in -perverts may ignore the pun- So, here today I bring you a collection of oft-used Latin phrases in English language. Did I hear a collective sigh of relief? All right, all right don’t cry now and tell me ‘Suman What’d we have done without you!’ So, as I walk into the bright orange sun-set like the traditional hero... You guys go take a look at the Latin phrases. It’s ‘Sine Qua Non’ baby!
http://depthome.brooklyn.cuny.edu/classics/englatin.htm
write to me: Suman@sumankumar.com

2003-08-12T23:48:00.000-07:00

Importing Word2000 Documents to RoboHelp HTML

Article on Robohelp Community

Above article in Flash-help format
write to me: Suman@sumankumar.com

2003-08-10T23:32:00.000-07:00

How to hire a 'Future-Proof' Technical Writer

I came across quite a few recruitment ads in the papers and job announcements in mailing lists that ask for a technical writer. It is good to see that the demand for my ilk has shot up. What’s appalling though is the emphasis that the companies place on a tool: ‘should be acquainted with ‘ALL’ features of FrameMaker’ or ‘experience in writing for semi-conductor chips a must’.
Here’s my take:
My complaint is very few of them actually are bothered about writing skills. I know that writing skills alone don’t make a good technical writer. A good perspective of technology and writing (to an audience) skills do.
I’ll speak for the IT industry: A tech writer should NOT be code-phobic. She should have excellent interviewing skills. Should be a friend. Should have a lot of patience (your SME can get on your nerves I am telling you). She must die for her users… (your boss may slap your back and say ‘atta girl! It’s looking great.’ But if your user doesn’t understand what you’ve written or can’t navigate through your documentation, it is not a blot only on your skills, but also on the product). So writing to an audience is something that I’d look for when I am hiring a technical writer.
Let’s go for the tools now:
Tools change. Say that again aloud. And learning a new tool doesn’t take time. I am positive that any good technical writer can pick up FrameMaker in a week’s time. But being an expert at it? Go for a desktop publishing person man.
I have no problems understanding technology; the APIs, the chips, the front-end processing, the database… I’ll understand it all. I’ll interview your SMEs, I’ll study code, and I’ll move mountains to ensure that the technical nitty-gritty is translated into something that your user understands. But don’t go ‘a technical writer with expertise in FrameMaker, RoboHelp, XML, SGML, HTML, Java, C++…’ Gimme a break will ya?
I am not saying that a reasonable level of expertise in popular (they wont remain popular for long though) tools is not required. What I am saying is, if your candidate were good she’d be comfortable in most of the tools. If she’s not an expert in FrameMaker or Snag IT don’t write her off for god’s sake. Don’t pin your technical documentation to a tool. Pin it to a person. A person that understands the trade, the users… as I said, if need be that person will pick up your tool.
Also, it’d be nice if your technical writer knows how to break the rules. I mean I know a lot of writers who guard the English Grammar with talibanistic zeal. If I were you, I’d bother about the ‘usability’ of the error message than its grammatical integrity.
Let’s summarize it: Don’t confuse writing and publishing. They are two different domains. A good writer needn’t be a great publishing expert. Look for a person with a good technical perspective, impeccable writing skills, user-focus and integrity. If I can’t (wont) stand up for my user, I can go home. So my dear reader, the next time you go shopping for a technical writer, remember “Tools change.”
If you listen to me you’ll get yourself a ‘Future-proof’ technical writer. If you didn’t you got yourself a Johnny. And I won’t be surprised. ;-)

Related Links:
FrameMaker
RoboHelp
SnagIt
AuthorIT
Irfanview
HTML Kit
Swish
[Note: There are a million tools out there. I have listed what I use.]

write to me: Suman@sumankumar.com

2003-08-08T06:05:00.000-07:00

AECMA Simplified English

What Is Simplified English?

AECMA Simplified English is a writing standard for aerospace maintenance documentation. This type of writing standard is also known as a controlled language because it restricts grammar, style and vocabulary to a subset of the English language. The main characteristics of the Simplified English standard are

Simplified grammar and style rules.

A limited set of approved vocabulary with restricted meanings.
A thesaurus of frequently used terms and suggested alternatives.
Guidelines for adding new technical words to the approved vocabulary.
The objective of Simplified English is clear, unambiguous writing.
Developed primarily for non-native English speakers, it is also known to improve the readability of maintenance text for native speakers.
AECMA Simplified English does not attempt to define English grammar or prescribe correct English. It does attempt to limit the range of English; many of its rules are recommendations found in technical writing textbooks. For example, SE requires writers to:
- Use the active voice.
- Use articles wherever possible.
- Use simple verb tenses.
- Use language consistently.
- Avoid lengthy compound words.
- Use relatively short sentences.

Other Controlled Languages

While AECMA Simplified English is designed for use in aerospace maintenance documentation, controlled languages can be created for other writing domains. Companies in several industries -- manufacturing, mining, oil exploration and software development, for example -- have modified AECMA Simplified English or produced their own controlled-language writing standards. The Boeing Simplified English Checker can be modified to support more general technical writing.

Related Sites:

AECMA (European Association of Aerospace industries)

simplified English

write to me: Suman@sumankumar.com

And now, 'Technical Writer': The Movie

2003-08-02T06:08:00.000-07:00

And now, 'Technical Writer': The Movie

A
movie on a technical writer!
[Through Usable Help]

A Tale of a Technical Writer who did Programming for Fun

2003-08-02T05:41:00.000-07:00

A Tale of a Technical Writer who did Programming for Fun

V Srinivas on the TWIN list wrote:

Hello Twinners,

I must say I have been keenly following the views and opinions that have
been coming up regarding the usage of online help tools.

First of all, I would like to say that I wouldn?t want to spend much time
in ?creating? an online help file. I would rather spend time
in ?improvising? and ?thinking? about how I can make that Help file reach
the audience better. And that too, I would want to have some TIME on my
hands to do that.
I definitely wouldn?t want to spend precious time in doing work such as
copying and pasting.

>From my experiences, I can roughly put down the following statistics
relating to the thought process and labour that goes into creating manuals
and online help.

Creation of a User Manual may involve: 100% Thought Process Creation of
Online Help may involve: 10% Thought Process + 90% Labour / Mechanical Work

Which means, most of the time has been spent in copying and pasting content,
creating HTML files, building TOCs, creating indexes and so on. And
annoyingly, I was all the time aware that they are already there in the
user?s guide and that I was doing the same thing again. Sure, there are
tools in the market that can take care of the 90% labour but we are a little
wary of the price tag. Also, I have been a size fanatic. I have always
wanted my HTML files (and the resultant CHM) to be as compact as possible.
To add a few more wishes, I wanted them as ?readable? and ?editable? as
possible. In other words, I didn?t want a thousand unnecessary HTML tags to
get stuck in my document. For a live demonstration, just convert your
document to HTML using Microsoft Word So I started using RoboHelp. RoboHelp
was good ? with its good user
interfaces and other powerful features. But again, it was the same old
story. I had to still do the copying and pasting, which I loathed so much. I
still had to build a TOC (when in reality, I already have done the thinking
in structuring the TOC in Word itself) and I had to still worry about
getting the images right and stuff like that.

So, I abandoned these tools altogether and started working with the HTML
code itself. For this, I wrote small macros in Word to start tagging the
document manually. So, for about six months, I depended on two major tools:
1. MS HTML Help Workshop (for its simplicity) 2. MS Word
But I was not happy. For example, for a 75-page user?s guide, I took almost
about 3 and half-hours to convert it to online help. I will not bother to
tell you how much time I generally take for converting a 233 page user?s
guide.

Automation was the only answer. And I jumped to the occasion. For a start, I
started examining behind the scenes of a .HHP project ? how the project was
being structured, how the TOCs were structured, the indexes and so on. I had
a fair idea about the HTML part of it, because I was manually tagging the
document.

I used Microsoft Visual Basic to experiment on simply because it was so easy
to understand. One afternoon, I started playing with a Word object and
slowly but surely, my dream of automating user manuals to online help turned
into reality in the weeks to come. Some parts of it were tough and bothered
me even in my sleep but I must say, that it was a lot of fun solving one
mystery after the other. I should say, identifying and tagging the bulleted
lists and numbered lists really did bother me a lot.

BUT I DID IT!

On the afternoon of July 25th, 2003, I couldn?t help feeling a little
elated. I fed a user manual (65 pages) to my program and it took exactly 4
minutes to do all the conversions and present me the online help project on
a platter (.HHP). Another 3 seconds to compile the project and I was THROUGH!

Sure, there are still some downsides to the conversion process that I am
working on ? for example, the program is getting a little confused when it
tries to convert a table, which has merged rows/columns. Also, my program
requires that all the images should be linked to external files. I should
perhaps find a way to pick the image (linked or not) inserted in a word file
and save it to a JPEG ? now that would be something. Another downside is
that it can generate only two levels of TOC. I can in fact defend myself
saying that after the second level, it is up to us to decide whether some
content needs to be grouped into a third level and so on.

But the fact is, the program (HTML Help Express) at least gives a good kick-
start to my whole process of creating online help. It may not be the best in
the industry, but hey, it?s a solution. It can prove to be a fairly decent
in-house tool for technical writers in our company and I had a fantastic
time in developing this. And of course, I had a fantastic time in my company
explaining politely to everybody that it was a TECHNICAL WRITER who
developed the software.

So who said that Technical Writers are ?not? technical? Who says that it is
only ?they? who develop and we ?just? write? Technical Writing has been
recognized as an IT enabled service. And I feel that while we write about IT
products, we should also simultaneously use the power of IT to improve and
automate our own work processes.

Regards
V. Srinivas

2003-07-29T08:03:00.000-07:00

PowerPoint Resources

Excellent site for some real cool 'free' templates; and for some essential tips and tricks. Betty sure is Brainy! Check it out.
http://www.brainybetty.com/PPTIndex.htm
write to me: Suman@sumankumar.com

2003-07-02T09:12:00.000-07:00

Using Blogs to Collect Information

I am experimenting this idea. I have set-up a blog (using Nucleus. This is what I did:
1) Met all the technicians I had to.
2) Told them about how they can provide information now through a browser based 'site' that'd allow them to 'blog' their ideas/suggestions
3)I created user ids for all of them for the Intranet blog and mailed them the same
4) I also told them they can use the 'right-click to blog' idea. Like Blogger, Nucleus offers a 'right-click->Blog this' feature

It's worked out ok for me. I mean not all took to the idea. But some did. That's a start! Have you tried something like that?

2003-06-03T22:08:00.000-07:00

Content Management Systems

Here's a list of CMS that I found to be very useful. AND easy to implement.

Nucleus
B2
Drupal
Envolution
All of the above are PHP/MySQL based. Now, I don't know how to code with PHP nor am a database guru. That must tell you how easy the above tools are to implement. (Disclaimer: that doesn't mean someone who has never seen a computer can implement them, you get the drift?)
For more PHP/MySQL based scripts visit the 'content management' section of hotscripts

2003-04-13T05:25:00.000-07:00

Web Writing

From Sun.com:
You can double the usability of your web site by following these guidelines: for two sample sites studied in Sun's Science Office, we improved measured usability by 159% and 124% by rewriting the content according to the guidelines.
Writing for the Web is very different from writing for print:

79% of users scan the page instead of reading word-for-word
Reading from computer screens is 25% slower than from paper
Web content should have 50% of the word count of its paper equivalent

The User-Friendly Manuals' Website

Check out the site at: http://www.prc.dk/user-friendly-manuals/

2003-04-12T12:54:00.000-07:00

Technical Communication Mailing Lists

http://www.stcatlanta.org/maillist.htm

2003-04-12T04:51:00.000-07:00

The User-Friendly Manuals' Website

2003-02-06T16:21:00.000-08:00

The Seven Deadly Assumptions of Technical Communication - William Rice

Years ago, as a young programmer/analyst on a project leader’s course, I made an assumption during a team exercise. Not a crucial mistake, you would think. I assumed that I had all the information I needed to complete the exercise. I also assumed that the exercise was about interviewing a potential employee. In fact, the exercise was actually about the danger of not identifying and confirming assumptions before blindly rushing on with the task at hand.

In this article, I identify seven areas in the field of technical communication where unconfirmed assumptions can lead to a waste of time and money and also undermine your credibility. Read more

2003-02-06T08:17:00.000-08:00

Useful links for technical communicators

http://www.prc.dk/user-friendly-manuals/ufm/linklist.htm has some great links/resources. This resource is Edited by Peter Ring, PRC - Peter Ring Consultants, Denmark.

2003-02-06T08:11:00.000-08:00

Dictionary of Plain Language

Found this on techcommunicators.com. To check out the dictionary go straight to: http://www.techcommunicators.com/diction.html Hope you find it useful.

2003-02-01T07:25:00.000-08:00

Online Help: Choosing a Tool

There was discussion on the TWIN mailing list about online help and Alfred had this to say about that:

Hi
Another issue with .chm is that you (the end user) have to download the entire file when you're accessing the help system. That might not be such a good idea if your users are accessing the app over a network. Usually for web-based applications people tend to use a HTML-based help system (like WebWorks Help 3.0) or just plain HTML with searching and indexing capabilities.
I would advise you to think about these issues (and others) before picking a tool or a format. RoboHelp might be used by everyone in India (just as an example) but it might not be the best tool for you. Maybe AuthorIT does what you want. Evaluate the tool, its limitations and whether it does what you want it to do. I guess what I am trying to say is that you should make an informed decision.
Alfred

Writers India: Technical Writing and Design Communication

This blog has moved...

The Personable Manual

Promoting Document Usage: Taking a leaf out of Business Directories

Comics and Technical Communication

Tech Writing Manager? So What?

Use it before you write it.

The Zoho CRM User Manual

My STC India Annual Conference 2007 Slides

I will be talking at the STC Annual Conference in Goa

Citibank Online Banking: Bad Example

How often...

Documentation: Google Style

Adobe to Release PDF for Industry Standardization

Adobe PDF flaw: more serious than first thought

The Science of Word Recognition

STC Annual Conference: I will be presenting a paper

Google to Merge Writely and Spreadsheets to Form Google Docs

A technical writer's worst enemy is another technical writer

Use Old Words When Writing for Findability

Quality of Communication

Death to Caps Lock

A Comma Worth $2.13 Million

e-learning 2.0 - how Web technologies are shaping education

Technical Writers of India (TWIN) Portal Launch Today!

One Billion Users and Counting

Documentation in RSS Format

10 Ways to Please Us, the Customers

Top Ten Documentation Heuristics by Vesa Purho

Engrish!

MS Office 12 to Support PDF

Aah?

Tech writer or DTP Expert?

A brand name gone wrong

Interactive Documentation

Review of Screen Capture Tools

Microsoft goes the RSS way

To Click or Select...

Need inputs: Talk on usability

Prepend

GUI Glossary

Enhancing Internal Communications with Blogs, Wikis, and More

Merry Christmas Folks!

Comments System: Anyone Can Post Comments Now!

Hollywood May Hire You!

Firefox: Tech writer friendly!

Tech-writers – A Necessary Evil

Wipro blogs!

Switching careers: Madman's story of making a business out of one's passion

Off shoring of Documentation: a survey

Writing SI units and symbols

Travails of a tech writer

Finding the voice

Oxford Plain English Guidelines

FAQ from Gregg Reference Manual

Wanted: Sr Technical Writer for Informatica Corporation

Style guides: Sacrosanct?

Wanted: Technical Writers for Wipro Technologies, Pune

Job openings for young under-grads and graduates in Spectramind

Rush your resumes to one of the following e-mail ids

Installing a gas stove: Why I think technical writers are important to this green earth

Context Sensitive 'Sticky Notes': Stick a Sticky Note to your Blog!

New resources for tech writers in India

You are Invited

Opportunity: Tech writer for developing dictionary of terms

WebWorks Publisher 2003 - An introduction

Microsoft Longhorn Help: Highlights

Technical Writing Glossary

Participative Help Design

Participative Help Design

3rd STC Chennai Meet this sunday.

Localization and Internationalization

Localization and Internationalization

In Denver

I am engaged

Usability Testing of Your Documentation

Microsoft LongHorn Help

How to become a technical writer

All writers are not technical writers

Tools