Presented by : Mahesh Ramakrishnan i-flex solutions limited December 2001 Purple in your Face Better ways to documentation

There was a guy who had just bought a new PC. Had some trouble loading a new utility he had purchased that came on several 5.25" floppies. Called the service tech, who said the floppy drive may be bad, send it in for replacement. When it came, the door was open, and several floppies were jammed inside. Tech pulls out extraneous floppies - drive works perfectly! Calls guy and asks... WHY!!! Guy says program told him..."insert Disk 1, insert Disk 2, etc." Didn't say nothin' about taking any disk OUT!

Documentation is all about Communication

Purple in your Face Better ways to communicate

So.. Who is a tech communicator  Some one who has good language skills  Some who has good grammar  Some who loves writing  With a dash of humour  Ever patient..  Willing to work with Programmers!!!  So.. What about Technology!!!!!

Yesterday’s World  User Manuals were the order of the day  Followed by Technical Manuals  Usually written by programmers themselves  Manuals were hard to understand  Manuals were even harder to use  Often a days work has gone into it..  They were more philosophical than a guide.. with some screens thrown in..

Today’s World  Programmers do not write Documentation  Tech communicators do!! Today’s Systems  More complicated systems  More interactive systems  More intuitive systems  More onscreen interaction  So what happens to the Paper Manual!!!!

Will Anyone Read a Tech Manual!!!  To be a hit, technical manuals--like other products-- need to appeal to their intended audience.  Only documents –that are easy to use and understand, –that are visually attractive, and –that meet the expectations of the audience will be read with pleasure. What Expectations… Have you seen a programmer read a user manual the first time they use a system!!!

Programmer Facts  Programmers read user/technical manual only when they have problems –The criticality of the need is the greatest then  They expect to find a solution to their problems –The manual must address almost every need  Once not found.. The manual is rarely used..  Once found.. That becomes a Bible…

A Tech Manual – A Best Seller!!!  Well, it is possible, as evidenced for example, by the millions of copies sold under the "Dummies" name of computer manuals.

KEEPING the Hope alive  In recent years, some encouraging signs have been emerging within the documentation field.  Organizations have recognized that in documentation, you get what you pay for.. That must be good for all of you  While few people would likely purchase a product based solely on the quality of the accompanying documentation, those same people may view the entire product as inferior if accompanied by poor documentation.  Companies have consequently been devoting more resources toward their documentation efforts, with the aim of creating better documents.. for the purpose of better communication and interaction between systems they produce and the users..

The new age tech writers… Basic System rules  Software must assist the user perform a task, not become a task in itself  Software must not make the user feel stupid  Software must not make the computer appear to be stupid Communicating with the user is a paramount need.. And tech writers have a important role to play in this… This requires that the role extends beyond just transcription

What tech communicator’s need to do today..  Get Involved in user-centered design  Make the interface to the help system  Help Bring features forward  Check spelling and grammar  Make wording consistent  Eliminate jargon  Show the user what to do  Improve error messages  Constantly Communicate  Specify to the programmers

Creative Writing

This is how messages often appear to the user. System messages are the antithesis of proper application design. They are often ambiguous, rude, and all too often, incorrect, blaming the user for failures of the programmer.

Some Examples… Error messages are often invasive and rude, halting the current activity, and demanding that you acknowledge them before you are allowed to continue. If your friends acted this way, they wouldn't remain your friends for long.

The Changing world Online Help Manuals WEB Pages F1 Help Error Messages User Interface

Today’s Tech communicator  Needs to be more tech savvy  Needs to understand the application  Needs to know beyond documentation  Needs to work within the team  Needs to provide a outside perspective

The good tech communicator is still…  Some one who has good language skills  Some who has good grammar  Some who loves writing  With a dash of humour  Ever patient..  Willing to work with Programmers!!!  Knowing technology and the application.. Will be the great differentiator

THANK YOU Merry Christmas PURPLE IN YOUR FACE What was the title all about