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

Read More

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.

Read More

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.

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



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



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



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



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



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



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

Read More

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

Read More

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

1. Patience to research
2. A knack for collecting information from various sources
3. The skill to write in simple English. Write less, say more if you will
4. Excellent inter-personal skills: you'll be interacting with technicians, users and managers, and trust me, it is not easy (especially the technicians :-) )
5. 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:

1. Freeze on target company
2. Study target
3. Identify contacts
4. Tweak/build resume
5. Write a nice covering letter
6. 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!

Read More

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

Read More

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

Read More