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

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

Read More

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

Read More

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

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

Read More

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

Read More

Re: [twin] Course Content for Technical Writing

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

Read More

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

Read More

Importing Word2000 Documents to RoboHelp HTML

Article on Robohelp Community


Above article in Flash-help format

write to me: Suman@sumankumar.com

Read More

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

Read More

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

Read More

And now, 'Technical Writer': The Movie

And now, 'Technical Writer': The Movie

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

Read More

A Tale of a Technical Writer who did Programming for Fun

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

Read More

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

Read More

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?

Read More

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
  
  
  
  

Read More

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
  
  

More on sun.com

Read More

The User-Friendly Manuals' Website

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

Read More

Technical Communication Mailing Lists

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

Read More

The User-Friendly Manuals' Website

The User-Friendly Manuals' Website

Read More

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

Read More

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.

Read More

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.

Read More

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

Read More

User Manual for Building Your Own Plane

The manual is actually an image. Check it out and let me know if you liked it! ->Build Your Own Plane<-

Read More

How to save your client $1600 per task per year through Usability Testing

I have noticed quite a few mails asking how to conduct a usability test or how to interpret the results of a test. I thought it'd be a good idea to give you all a set of documents that resulted out of a usability test. I have changed the actual information for reasons of confidentiality, but it should give you a good insight of what a usability test is all about.

What is a usability test?

It is testing your product on actual users to find out 1)If your product is easy to use 2)If the navigation is user-friendly 3)Get 'feature' ideas to improve your product 4)If users were able to perform their tasks efficiently, and within acceptable time limits, and 5)To measure the 'joy of use'

To me, the most important metric is the 'task-time': When a user is taking longer to perform a particular task, that means something's wrong; could be the navigation or it could be the color scheme you chose or a combination of such common mistakes. Why is task-time important? If you can reduce the task-time of a particular task by say 30 seconds, and your product is used by a 100 strong company; and this task is a daily task, performed at least once... you have saved your client from a productivity loss of: 50 minutes per day. OR slightly over 4 hours per week. Assuming all 100 are paid $10 per hour. We are looking at savings of $40 per week PER TASK. And if your client works for 40 weeks in a year, you are looking at $1600 savings only on a simple task that users perform on your product. I may be indulging in some wishful thinking here, and maybe my math is terrible, but whichever way you look at it, usability does save money. There are other reasons why usability testing should be adopted in your development process, but I choose not to discuss them now. Shall write a separate piece on that later.

What is the Think Aloud method?

1)Identify actual/representative users (five users is my advice)

2)Make a list of tasks (example: Search and find the currency of Honolulu)

3)Choose a location where your users are comfortable; a location that reflects their working environment.

4)Notify users about your usability test. Send invites. Follow it up with a phone call or e-mail and confirm their participation.

5)Explain that they are not being tested, the product is being tested. Give them the tasks. Ask them to keep thinking aloud (say it as soon as a thought enters your mind!). And YOU shut-up!

6)Observe users. Their expressions. Those small clicks of the tongue indicating frustration. Those non-verbal hints (scratching one's scalp rapidly, in one short burst OR those little shrugs indicating helplessness) NOTE IT DOWN. ALL OF IT. Tell them they can abort a task anytime they want to.

7)Use a Dictaphone to record comments. Note down the time per task. (check with them if you can tape them)

8)Take the satisfaction survey (to figure out the 'joy of use' of the lack of it thereof)

9)Thank them and give them a nice gift (some people give cash, but I give dinner coupons)

10)Repeat steps 1 to 9 for all five users.

11)Sleep on it. Compile a report next day.

Usability Testing DOs

*Smile. Be a friend. Don't be this geeky dick. No one likes them.

*Observe. I can't stress its importance enough. You got to be a keen observer. You have to record what was 'unsaid' too my friend.

*Listen: Talk less. Do more. Give non-verbal cues to the user like nodding the head or through 'uh-uh?' 'Oh yes.' 'and?' 'hmmmhmmm?' You know.

Usability Testing DONTs

#Don't help the user perform the task. We are here to find out how 'intuitive' the product is.

#Don't crowd on the user. Give him/her the privacy that is needed.

#Don't interrupt when the user it talking to you. Your words can wait.

#Don't get too personal.

[These are by no means comprehensive. I am just jotting down whatever came to my mind. If you have some more, do contribute. Mail me to learn how]

Usability testing: Sample reports

->Download Sample Documents<-<

The zipped file contains:

1)Participation Questionnaire

2)Task-time report

3)Satisfaction survey

4)Task-sheet example

->Download Sample Documents<-

Disclaimer: Most of the surveys were based on the STC usability kit. I am still working on customizing these documents for my use. So use your discretion.

Read More

Job posting: Thanks to the TWIN List

I haven't linked the e-mail ids and instead of '@' I have used 'at' this is to prevent the spam-bots from picking up the e-mail ids. Don't want the Quinnox guys ending up with great offers for penis enlargement - suman

> Quinnox urgently requires Communicators for its Mumbai operations.Quinnox, a global Business Solutions group headquartered in the US, is focused on providing high-technology solutions and services to world-wide clients in the areas of e-Business, ERP, Enterprise Value Chain Solutions and Outsourcing. Our services include world-class software development, consulting, systems implementation, integration and outsourcing.

> Our unique strength is our long-term relationship with customers, who have benefited from our end-to-end IT solutions. We stand differentiated by our emphasis on a service-management culture of speed & flexibility, trust & integrity.

> Since its inception in 1996, Quinnox has successfully executed over 400 software consulting, development and implementation projects in over 38

> countries. Our operations are executed from 9 International offices and 3 world-class Global Solution Centers.

For more information, visit http://www.quinnox.com



TECHNICAL EDITOR/WRITER

Job Description:

> - Editing/writing of business proposals, software project document deliverables including system 'Help', white papers, quality-related documents - both software and other function-related.

> - Creating templates for various categories of technical documents.Providing in-house training in technical documentation.

> Qualifications: Graduate/Post-graduate with an added qualification in Journalism/Mass Communications/Technical Documentation; Very good communication and interpersonal skills; adequate experience with word-processing/document designing/publishing tools. Five years of related work experience in the IT industry.

> E-mail your resume to: career(at)quinnox.com by 31st January 2003.

>

> ***************************************************************

> Quinnox Consultancy Services Ltd.

> (Formerly iS3C Consultancy Services Ltd.)

> 170, SDF VI, SEEPZ, Andheri(E)

> Mumbai 400 096, INDIA.

> Tel: +91 22 2829 0100, Extn.253

> Cell:+91 9820093589

> Fax: +91 22 2829 1131

> E-mail: virend(at)quinnox.com

> www.quinnox.com

Read More

Role of a Technical Writer: Mail to the TWIN List

Let's look at it the other way around. There are still a lot of organizations that do not have a documentation team. It is done as an 'add on' by the developers themselves. When you have tools like Robohelp, AuthorIT or those little beauties that abound (for free at times), that help you generate .hlp or .chm or xhtml... developers find 'presenting' information easier. So I had one of these developer friends remarking 'what's the big deal man? If I want to I can learn Robohelp in a week's time and I can become a tech writer.' I don't want to go on about how untrue his statement is. While the temptation to be a jack of all trades is overwhelming, please be warned that, writing as a skill, evolves over years. Writers tell stories. Applying this to our profession, we tell stories too, on how a product works, or how to troubleshoot something. It is all a story. Forget developers, if being good in a language is a major criterion for becoming a writer, every english professor in the world should have churned out best sellers. No sir. No m'am. Writers write. And it is not easy. Writing well? Oh, that's an entirely different story. So the moral is, stick to one profession, focus, and mature, instead of talking about how one can do a million things. Yes one can. But what counts is 'What are you best at?'.

Now, talking about QA. In India most companies have a QA cell: Objective: Get those damn certifications. CMM4, 5, six-sigma da da da. Very few are sincere in 'following' the processes or having a process-driven organization. I have seen many companies get cmm4 now and cmm5 6 months later and something else a year later. Excuse me! My friend working in Prudential told me that they have set up the processes for CMM2, and have been following them for the past few months, but they are very nervous; 'will we get CMM2?'

So if you have any dreams of changing the world by being a part of QA, waky-waky, it could be all a sham pardner. So stick to writing. Focus. If there's any profession under the sun that takes decades to master, it is writing. most of us here have been here for what? a few years? We'll talk about taking over other domains, after we conquer our own. And on a final note, please learn to discern this: Content from presentation. I see a million mails on FM and CHM, but not so many on the craft itself, writing that is. What gives?

Read More

Hi

A first post here ... check this link which carries an interesting write about the contribution of Technical Writing to Apple Computers / Mac

http://library.stanford.edu/mac/writing.html

Read More

Writing Web Help

I have been working on online help for the past year. When it started I was overawed at the size of the product and the documentation we had to prepare. But I learnt a lot on my way. Here are some tips that you might find useful

1. Users don't read text on browsers. They scan. So highlight keywords, action words ('do this, do that')
2. Cut down 50% of what you have written. Brevity can't be stressed enough. Please remember that reading speed on a computer screen decreases by about 20-25%
3. Write in active voice
4. Write 'action first. Effect later' (example: Click 'OK'. To go to the homepage. AND NOT 'To go to the homepage click 'OK')
5. Write to a singular audience: Imagine that the user is sitting infront of you and you're telling him/her how to perform a task. People don't use your software in groups
6. Iterative document design:Build a prototype. Test in on users. Build. Test. Build Test... of what value your documenation is if it doesn't help me in performing tasks? I can't take it to bed to read it like a novel!

Read More

Calling all Graphic Designers

So you think you got style and spunk. You think your design and creativity kicks butt? Oh yea, I am lookin for ya ol' boy. I want you to design a logo for Technical writers of India weblog. Are you upto it? If yes, Get on it now and mail me your design. Shall announce the closing dates very soon.

What if my design is accepted?

Well, you can share the power and glory of tw-india blog. Your name shall be etched on the sands of time, along with acknowledgement right here on tw-india blog.

Let me know!

Read More

HI friends,

I suggest we should have some good Tech wirter related questions and answer sessions related to the variety of problems faced by the writer community.

Any suggestions/criticisms, anything related to the topic welcome



Debashish

Read More

Job Posting: European Co Looking for a Tech Writer (Chennai)

Hey people

read below. He wants a tech writer immediately. - suman

Walker wrote:

Hi Suman,

Thanks for the kind reply, I am working for a European based company called i7Software Asia Pvt ltd, who has its head office in Iceland. This is very urgent, i am looking at closing this requirement within this week. Please inform your friends...

thanks once again for your help

Regards

Randolph Walker [e-mail: walker@i7asia.co.in]

Executive - Human Resources

i7 Software Asia Pvt Ltd

# 20, Moores Road

Park Circle, 2nd Floor

Chennai 600 006

+91-44-2822 3861 /62

www.i7asia.co.in

Read More

Framemaker to Word Conversion

People, any idea about that? if yes let me know. I did a google on it but found nothing substantial. I was dreaming of a free conversion tool ;-) If you have any information on this let me know.

Update

Jayanthi Wrote::

Converting Word to Frame:

Method 1: For Frame version prior to 6:

1. Save the Word doc as RTF format.

2. The RTF file can be directly opened in Frame.

3. The fomating as in the word document and the template components will also come thru. You will therefore require to apply the reqd FM templates to the specific components. This can also be done on a globally for common components. For example: if the word doc has a component BodyText that needs to be converted to Body in FM do a search for the component and replace with the reqd component.

4. After applying the FM template it it recommended that you delete the extra components from the FM doc.



Method 2. For FM 6 onwards, Word docs can be directly opened in FM.

After that perform step 3 given above.

Jayanthi

[Thanks Jayanthi. This information now will become part of a 'Tips' database I am planning. Something like evolt. tips -Suman]

Read More

Toilet UI design (source: Prasanna from TWIN list)

Check out this intelligent UI design: http://maddog.weblogs.com/stories/storyReader$68



Thanks Prasanna Sivadas.

Read More

Directory of Technical Writers in Chennai : Hi ! I'm compiling a list of Technical Writers in Chennai. If you are one or know someone who is, I'd appreciate if you can pass on the contact details to me at Kiruba@Kiruba.com . We are looking at having monthly knowledge sharing meetings.

Read More

Interviewing the Techies

My current project involves interviewing the architects, programmers and other experts. Here are some observations:

1. Open ended questions like 'tell me about the security infrastructure' yield more information than topic-specific queries
2. They may have documents, but what's on their mind, or in those post-its in their cubicle, those little snippets that are crucial for the user, seldom reaches those documents. So dig, probe and be patient
3. Be courteous, smile, be a friend. They are the experts. Always mention this 'It'd be great if you can offer your expert opinion' who doesn't like a little acknowledgement?
4. LISTEN. Don't interupt when the expert is talking
5. Give cues. 'hmm hmm?' 'that's right' 'ah-ha' you know?
6. Write less and say more in your e-mails. They don't normally read through your short stories :D

Maybe there's more. Why don't you add it? Got your content provider id yet? Mail me suman1973kumar 'at' yahoo 'dot' com to be a part of this site. And showcase your ideas to the world.

Read More

What is Technical Communication?

It's the process of gathering information from experts and presenting it to an audience in a clear, easily understandable form.

These "experts" can be engineers, scientists, doctors, lawyers, or anyone else with a special knowledge of a certain field of study. Technical communicators gather knowledge from these experts by conducting interviews and reading previously published material. Read more at the STC website

Read More

Technical Writers of India

Welcome this is the first post. I am looking for contributors. Mail me sumank73 'at' rediffmail dot com. This is a collaborative weblog. Site is under construction but if you start posting now it'd start growing: 1)go to www.blogger.com 2)log in 3)click on technical writers of india and follow instructions. Mail me if you face problems. If you have interesting ideas, links, articles whatever! mail me, we can post it here. I am looking for web designers, information architects and usability professionals to build this site this is community work, so don't expect money, if you have the heart and the time. Let's talk! You can leave your comments by clicking on the 'comment' link. The number in brackets indicates the number of comments a post received.

Read More