Minutes of the Presentation at Adobe on 30th August

Date: August 30, 2008

Time: 10.00 a.m. to 12.30 p.m.

Venue: Adobe Systems

Session 1: “Documentation Document usability testing - How to kick start” by Rajdeep Gupta.

Session 2: "Ten tips for enhancing productivity at your workplace: Tools and Processes that can be used to get the most out of your working hours" by Preran Kurnool and “Getting the most out of your help projects: Tips and Tricks with RoboHelp and Acrobat" by Mallika Yelandur.

Rajdeep Gupta started the day’s sessions after setting the meeting’s agenda and introducing the participants.

Rajdeep noted that documentation usability testing could enable users to find information to accomplish a particular task or employ a particular tool in an easy and efficient manner. He emphasized that performing usability testing on documents requires a good understanding of the users and their constraints.

Technical writers and in-house resources could do the document usability testing within a structured and detail-oriented framework. Document usability testing also involves best practices, protocols, understanding and evaluation of user feedback.


Rajdeep also detailed the document usability testing process that he employed, and explained how the testing environment was set up, the resources were identified, and the time and budget were planned. He also presented a classification of “usability errors” that he found while performing document usability testing.


Event: Bangalore TW Meetup Session-Supported by STC India

He added that the errors found should be quantified to make technical documentation more usable.


In the second session of the day, Preran provided answers to how Adobe Acrobat Professional 9 could efficiently manage document reviews. Reviewers could collaborate on the review process by seeing and building on other reviewers' comments.

The comments can be uploaded to a central repository and sorted by author, date, or page. A Review Tracker monitors the progress of shared reviews. The tool allows participants to e-mail reviewers, send e-mail reminders, or invite additional participants to a review.

Mallika introduced the attendees to RoboHelp Packager for Adobe AIR (Adobe Integrated Runtime), which allows technical writers to convert existing WebHelp files created with RoboHelp 7 to a powerful Adobe AIR application.

After the WebHelp is generated, technical writers can run the AIR package to develop an AIR application and send it to the users as a single file (.air). The application allows the users to add comments to the Help file and create context-sensitive help.

The meeting ended with a vote of thanks by Rajdeep.

Judging a Technical Writer

I have been honored to know couple of tech writers personally, who are not only brilliant in their profession but are well-cultured human beings. Thus this sought them with well earned respect from every walk of life. How do you judge a technical writer?

Obviously,writing is the first criterion, which would stand out. When you say about good writing, what generally you analyze? I won't take names here, but good writers have an immaculate hold over their language. Thus when they are writing its all about the flow; they do not find it a hard terrain. These writers are inquizitive to the core.

Everthing surprises them and they seek for more. Lets talk about a writer in a health domain who suddenly got a freelance offer. The writer has to document on Mobile Technology. I tell you these writers would have googled and gathered enough information before they appear in an interview.

They don't see it as just another work, but the sheer pleasure of documenting a software product/ technology is more than a few dollars to them. These writers believe that if they can make a novice user understand the complexities of the product, they have done a great job.

Lets face the fact: Good writers are seldom available. So, when you catch one, try to sit and learn. I had been horrible in my prime of career (I guess am little better) but thankfully, I had a senior writer helping me out. He has been a learning experience to me.

After observing me for couple of days, he took me aside one fine day and gave me certain tips. He didn't ask me to change my writing style since he believed it was good, but he found it unsuitable for Technical Writing. He told me to go through a few of the documentation guides that he had delivered.

I went through and then he asked me to analyze with my documentation. I was at sea. The first noticeable feature of his writing was clarity. Good writers write in a very clear and simple language and even though it is complex, you'll find each and every line clear.

Gathering Information is the most essential factor in Technical Writing. Belive me as good writers will tell you,"if you can gather information well, 70% of your job is done. Poor documentation happens due to lack of proper information.

" I used to accompany with my seniors when they used to interview the developers and SMEs and the way they gathered information was so immaculate.

How to have a good technical writer placed in your company? Fortunately or unfortunately, there are no tools by which you can find out.

But, I guess you need to hire someone who has an interest in technology, someone who has a knack for learning tools and domain. Prepare a questionnaire where you can feature questions on Grammar as well as Technology.

I asked once someone to write the steps for preparing a cup of coffee. She couldn't write it properly. How on the earth could I expect her to write on something on Technology?

Learning with Me

For those of you who joined me for the first time- seminars, conferences, meetups, chatrooms, personal encounters etc, I am a learner. So, if the topic throws enthusiast glances-ah-this-dude knows everything, than you are completely mistaken. I am with a capital LEARNER. I have been in this technical writing industry for nearly 5 years now, and officially hold the designation of a Technical Writer and Lead Writer for sometime.But call me a WRITER,and I am more open to take you for a drink.

In the capacity of writing software, I have closely encountered with clients,managed project documentation teams, estimated the time and effort of projects and sometimes acted as a consultant. So, I am not going to talk anything about this NOW. Alright, when this opportunity knocked at my door of being a consultant for setting up documentation services for a company, I was like hmmm, ahhh, should I or not?

There are distinct possibilities that may arise and lead you to say NO. First and foremost, if you like me are working for an organization than please note that it's a dangerous thing. So get yourself to do a non-voluntary services. My first suggestion is consultant brings contacts. You work with clients in their spaces and you should try to build contacts in every fashion

Scrolling at your will

As you scroll to the bottom of the page, more content loads up. So there is effectively no end to the scroll (at least till the content ends) and no pagination.

A demo of this control is at:

http://www.symfony-project.org/demo/pager.html

The most seamless application of this is in Google Reader. I’ve been using it for a year, but never noticed the way content is added based on the scroll!

Epic Editor Session @SUN MICROSYSTEMS

Straight from the Assistant Organizer's Desk

Dear Readers,

At the very outset let me wish one and all seasons greets for a fantastic Xmas and a prosperous 2008. Don't forget to invite me for the new year party :) I promise I am going to behave well :)

Coming back to the subject this is the time of the year when I usually look back at the activities that Bangalore Technical Writers Meetup carried out for the year 2007. Trust me, we had lots of sessions and activities this year. But I'll keep the email short and crisp as some usability guru opined, "write less, illustrate more".

Let me begin: we had 9 sessions in the year 2007, and the topics covered were as usual varied and interesting. Topics right from "API Documentation" to "English Grammar" and "HTML Programming" to "Comics in Tech documentation" were discussed. We also had tools session on FrameMaker and Epic Editor.

This year also witnessed an association in the form of premier Society for Technical Communication- India Chapter getting associated with the Bangalore Technical Writers Meetup. STC India sponsors the Bangalore Technical Writers Meetup now.

We at the meetup have had always tried to spread technical communication knowledge to various quarters and have not limited ourselves to just corporate offices and institutes. I am glad to announce that we are getting invites from certain colleges to organize technical writing sessions at their premises. Incredibly encouraging.

Networking still seems to be a rage in the meetup, and this month we saw a turn around of more than 50 plus people. That's great! Also, considering that the meetup membership list has grown upto 652 (till last count), the day is near when we will touch the magic mark of 1000 :)

I still get queries as to the registration amount of the Bangalore Technical Writers Meetup. Let me clarify here: This Bangalore Technical Writers meetup is absolutely FREE and no registration charges are required for participation. This is something that we organizers have always maintained, and we will unless and until we have some unavoidable circumstances to face. So, feel free to just walk in anytime at the meetup, and we won't mind having a coffee with you :)

I also look forward to have you as a speaker for the meetup. If you have any interesting topic to speak on (pertaining to technical writing), just send across an email to me and CC it to Saravanan ( sara.techwrit@gmail.com) preferably before the 5th of every month, and we will be delighted to have that as an agenda for the meetup. However, please see that you give me some time to organize the sessions. I am sure you agree to it, meetup takes a bit of time :)

This email is incomplete if I forget to mention the constant support that we received from the entire technical writing fraternity, and trust me we are more than delighted. Couple of you suggested that the meetup should take some initiative to make younger generation more aware about Technical writing as Career, How to be prepared and how they can move on. Well, we will keep that in mind, and will organize sessions soon on that.

Looks like I have made quite a few sleepy by now :) Anyway, thanks for your constant encouragement.

This is your Bangalore Technical Writers Meetup. Make it the best.

Once again Merry Xmas and a Happy New Year!

Dating a RoboHelp Project

Things are pretty eventful in the end of the year 2007. I was slowly wondering after the Annual appraisals that nothing more wrong could happen in my life when I was startled by this. The date was day before yesterday (December 5th 2007), exactly a month remaining for my next birthday.

This is a project that involves me documenting a part of an Admin module, and I had finished it with great satisfication, when suddenly tragedy struck in the form of RoboHelp struck. Couple of things that happens when such things happen- agitated, furious anger and what not. I was feeling all the same but more because this was the first time something such as this had screwed up. I can't explain what anxiety I had developed. Can you believe a mamoth project of more than 50 topics gone for a toss?

I dialled in some no's for help but none could help. I emailed to a mailing list but things didnt sort out. And then, I started drinking water and thought of what could happen if wrong. I did some troubleshooting lessons, uninstalled the software, renamed the project files but none could favor me.

The next morning, I reached office and first things first checked if the project was opening in other systems but it showed the same errors. I called up a senior writer who showed me a ray of life and said "don't worry! it can be sorted out". Well, I must thank her for taking time out and helping me out in this.

Here a couple of things that you should when you get screwed up with a RoboHelp project:

Don't panick; it doesn't help.
Go to the project folder; rename the .mpj folder and check if it opens post renaming.
If NOT, check the .xpj file and try opening it. 90% of the time it should open.
If NOT, than delete the .CPD file and try opening the file again
It should work. Again try reimporting the html topics and create the project.
If nothing works, than you need to pray that atleast the HTML topics that you have created in are all order.

Video on Support Cases and Documentation

Vasanth's take on Support Cases & Documentation

Event: Bangalore Technical Writers MeetUp- Supported by STC India
Date: 24 November 2007
Time: Started at 11.00 am
Venue: BEA Systems India Pvt Ltd
Subject: Support Cases and Documentation
Speaker: Vasanth Vaidyanathan, Program Manager – Information Products Group, Sun Microsystems



The name of the attendees' and their respective companies are listed below:
1.Vasanth V- Sun Microsystems
2.S Gopal- Consultant
3.Binamra-
4.Anindita- Integra Microsystems
5.Sarala Prakash- Integra
6.Prabhjeet Singh- HP
7.Manoj Kumar- ACS
8.Rishi- ACS
9.George Abraham- Commit
10.Julie- Lantex
11.Binu PV- Mainstream
12.Sudhindra- Tejas Network
13.Vinay K- Consultant
14.Vaishali- Caritor/Keane
15.Anand- Caritor/Keane
16.Asha- Caritor/Keane
17.Immanuel- Caritor/Keane
18.Kumar Dhanagopal- BEA Systems
19.Paresh Naik- BMC Software
20.Vishakha Naik-
21.Sandeep B- Symphony
22.Gururaj BS- BEA Systems
23.Rajdeep- Infosys

After a welcome note by Rajdeep, Vasanth took the centerstage. He started by classifying Technical Documentation under the following heads:

•Installation and Configuration Guide
•Admin Guide
•User’s Guide
•Developer’s Guide
•Online Help
•Troubleshooting Guide
•FAQs



These documents will further differ depending on whether the company producing these documents are a product or a services oriented company.

Technical Writers should not forget their customers in their hurry to meet the deadlines of releasing the documents. They should make an attempt to find out whether the documents authored by them are being used by the customers. If they are being used, then what is their experience with it?

Next Vasanth suggested some ways to assess the user experiences with the documentation. One way of assessing the user experiences is to conduct docunentation surveys anong the customers. Such surveys can be a set of 7 to 10 questions asking customers to rate the documentaion in a scale of 1 to 10. These surveys can be indepenent ones or it can be bundled along with the product surveys; however, conducting such surveys will involve some cost and also require management sanction.

Another easy way to assess the impact of technical documentation is to get some periodical feedback form the Tech Support team. Technical Writers can network with their colleagues working in the Tech Support team. They can request the Tech Support team to share with them such case logs pertaining to documentation. Case logs are records of conversations between the customer and the Tech Support team.

Some of the case logs pertaining to documentaion could be:
•I am not able to complete my task even after following the steps given in the documentaiton
•I have been misled by the documentation and now I have a different set of problems
•I followed the steps given in pages numbers 6 and 7 of the XYZ documentation and it worked. Thank you.

Case logs may also leads to the following pointers:

•Which are the most and least document topics looked and used by the readerst?
•What is the kind of information the customers are looking for?
•Are customers looking for more Trouble Shooting Guides or FAQs?
•How can the documentation be delivered – books, blogs, wikis, screen casts etc?

Technical writers can use the valuable infornation collected from the case logs to do the following after discussing with their management:
•Rewrite some portion of documentation
•Prioratize and accordingly allocate time and manpower to various types of documentation
•Suggest elimination of some documentation or clubbing the same with some other books

This regular exercise will help the Technical Writers to focus on the needs of the customers. It will in turn reduce the calls to the Tech Support group and help their company save millions of dollars. Also, `Thanks’ notes recorded in the case logs will improve the self-esteem of the Technical Writers, enhance their standing in the company, and motivate them to further excel in their field.

The meeting ended with a general quiz – questions taken from various fields like cinema, IT, agricultual commodities, HR etc. – compiled by Rajdeep Gupta. There was an excellent participation. Nobody lost; everybody won.

The hosts provided the refreshments.

Please follow the link below for meetup photos:
http://techwriter.meetup.com/2/photos/?photoAlbumId=254532&photoId=2655254

You can also download the presentation titled ‘Support Cases and Documentation’ from
http://techwriter.meetup.com/2/files/

Hope to see you folks in the upcoming sessions.

Using Comics in Technical Documentation

This article of mine got published on the STC Usability Newsletter for October 2007 edition. Please follow the link http://www.stcsig.org/usability/temp_newsletter/0710-Comics.htm

I am also putting it below for an easy referral:

Using Comics in Technical Documentation

By Rajeep Gupta, India Chapter

Introduction

Over the years, I have wondered how end-users view our technical documentation, and have sought ways to make documentation livelier and more engaging. This article is based on the research and feedback I received from a number of user experience designers, usability specialists, product developers and writers, which led me to engage in a dialogue with the users.

How it started

I read an article by Rebecca Sedaca, and titled "Comics - Not Just For Laughs" (http://www.boxesandarrows.com/view/comics-not-just-for). The article described how she engaged readers by using comics to communicate concepts and encourage ecommerce. Her ultimate objective was to use comics as a communication medium where complex thoughts are broken down into a simpler communication style, and targeted at various audiences. I came away with the thought that a medium like comics could help us simplify the communication of complex technical topics, and engage the user at time with a 'fun' factor.

Why I liked this approach

Many people believe that technical documentation cannot possibly be made interesting, let alone fun. Most printed technical documentation sits on shelves, often untouched for months or years at a time, and only read when the need arises. Perhaps a new method of communication could make documentation more interesting. I decided to try my hand at this technique. I first considered a chat messenger, and decided to come up with some help files.

Which are the various technical documents deliverables to have comics

I think comics could be handy when you are delivering a safety manual for pilots or passengers. Instead of capturing information points by points in a text, use comics to display the information. In addition, in cases wherein you are writing a manual for a mechanical product, we can use the comics to display the complexities. A user guide or an online help can have comics embedded in it.

Why is it a bad thought?

If you believe the premise that comics can increase the use and usability of technical documentation, it is important to note that there are limits to their usefulness, which may include:

Comics and cartoon actions and characters can be interpreted in different ways. What may seem creative to the writer could be offensive or upsetting to the reader.
A lot of thought must be put into every aspect of the comic. For example, the way the character looks and dialogue will be viewed differently by different readers. You must make an effort to ensure all types of readers will come away with the message you intend.

It is easier and less expensive to fix problems with text than with cartoons, which are drawn graphics.

Children are much more comfortable with comics than adults. Adults are typically engaged only by clever or witty comics. In trying to make the comics appealing, you do not want to sacrifice informational content. Even if you develop an informative cartoon, an adult reader may find it distracting or intrusive, rather than informative.

When viewed for the second or third time, a comic may lose its charm. If a user wants to refer to the technical document again, the comic may be less engaging than when initially seen.

Printing costs may increase if you use color in your comics, or if they add significantly to page count.

Translation of graphics costs more than text translation, and accommodating cultural differences may require redrawing of a comic.

Suggestions

I spoke to a few professionals and here's what they suggested:

Analyze the interaction between the audience, the content, and the drawing. Because a cartoon may trivialize the material, you must assess whether and where comics can contribute to the documentation at hand. This could be accomplished when the technical writers perform a documentation analysis before they begin writing the first draft.

The panel structure of comic art is a nice way to show a sequence of actions, because the time concept is built into the design pattern. Using a non-realistic style also allows the artist/writer to over-emphasize critical details or adjust the "view" to make small details easier to see.

Comics might also be an effective way to engage readers who might not typically turn to a book for instruction. An example could be cited of the United States Army using "comic books" for manuals for heavy equipment, and as well as ease of communicating "service bulletins" to the mechanics in the maintenance departments.

As with so many aspects of user experience, the critical factor here is to understand the users and their context of use, and to make design decisions to enhance usability (for the appropriate people, in their context, to meet their goals).

An in-depth understanding of the culture must be mapped to the technical documentation effort on an ongoing basis. This is one of the critical factors in ensuring successful use of comics.

Anything that reduces cognitive overhead in communication is welcome. Whatever the medium, usability testing on the deliverables is recommended.

Conclusion

I am developing help files that use comics as an interactive medium. When finished, I will forward it to my colleagues for their feedback. Using comics as an enhancement to technical documentation is worth considering. The more experience people have with this technique, the better they will understand how and where comics can best be used.

9th STC ANNUAL CONFERENCE@ GOA

The air around CIDADE DE GOA at Dona Paula was bearing a sense of expectation from Thursday (October 25, 2007)to Saturday (October 27, 2007). There were excellent reasons. For the next 3 days, CIDADE witnessed congregation of technical writers, editors, managers, instructional designers, web designers, and usability engineers etc to celebrate the 9th STC Annual Conference.

Laced with colorful scenic beauty of beaches and palms, GOA witnessed various knowledge sharing session ranging from Blogging to Heuristic Evaluation, to from Web 2.0 to Managers forum. It had something for each one, and in the end it aptly testified that STC India has managed to bring another event to a resounding success.


The pre-conference workshop was the starting of the gala event which lasted for three days. Francis Anthony (Synopsis) was the EMCEE for the event who infused a sense of charm in the sessions. The inauguration took place at 6 PM with the five STC representatives lighting the diya.

26th October 2007:
As time was limited and multiple presentations were to be delivered, so the organizers had to conduct multiple sessions simultaneously, hence it was left to the delegates to choose and attend the relevant sessions. Brian Keefe (EMC) started with the session on getting ready for the next wave in which he spoke about the induct ion of new trends and technologies in technical writing.

Next, Francisco Abedarabo (Oracle) who enthralled the audience with his wit and humor. The interesting part was the way in which he used the presentation as an aid. He provided certain tips on the American manager’s perspective on Indian writers wherein they mentioned improvement on writing & communication, language skills, a neutral writing style, flexibility; Francisco also advised the Indian writers to follow global processes and learn project management skills.

Suman Kumar (DELL) presented a session on 'If you agree, click "No!", and Ravi Kumar (SUN) on Demystifying Localization. It couldn't get much better as the next item was a debate on whether 'Technical Writers are overpaid or not?' It was pretty interesting to hear as Sameer Chabra, Vasudha Singh, Rachna Ganguli and Udhay Chava infused the audience with their pointers though majority voiced of same opinion- technical writers are NOT being overpaid. Gururaj BS moderated the debate.




After a delicious lunch, the participants were ready for some more interesting sessions. Rachna Ganguli and Shilpa Sharma from Cadence provided us with a session on 'Test Plans been a source of documentation quality'. They thought that a lot of information could be used by writers as an aid for their documentation. Couple of sessions were running at the same time- Shripad and Peter Fernandez (SUN) spoke on collaborative content, while Denise Kiser (Vmware) spoke on the necesarry qualification for a technical publications manager

All through out the conference there were constant interaction amongst the speakers and participants were constantly networking themselves. It got more interactive as Vivek Jain of Adobe presented the session on Adobe Technical Communication Suite. It was a pretty engaging session in which Vivek highlighted the capabilities and features of Adobe suite.

A break was taken for 15 minutes after which the much awaited panel discussion on technical writing in India. Fred Menezes presided over the session and the panel discussion included managers from different companies and discussed on Technical Communication- past, present and the future.



Edwin Skau (Juniper Networks) conducted the prelims quiz. It kept the participants engaged and was pretty interesting to find the enthusiasm amongst the people. Next, the stage set up for a river-cruise. In the arch lights of Panjim city, Goa was a beauty to be viewed and writers showed that they could match the best of the professionals when it came to dance.

27th October, 2007:
The final day of the conference begun with Manmohan and Jayalakshmi of CA putting together an interesting perspective on the global collaborative technical publications organization. Next, Makarand Pandit (Technowrites) set the stage on fire with his presentation on the business management lessons. Mak shared some simple, yet hard to find realities of our work world in "The business management lessons I learnt from my gardening hobby."

Mak used his garden theology to put forward his management perspectives with suggestions just as a plant requires food and water for survival and to turn itself into full-grown tree, similarly experienced professionals need to tap in the budding youngsters or juniors to make them grow as excellent individuals and workers.

Infosys had a pretty interesting presentation lined up with Amit Bhatia delivering a presentation on Usability Evaluation of Help. Most of them had a query on whether Heuristic Evaluation was same as Usability Testing. Amit showed excellent skills in responding the queries. Suraj Jayan (HP) took a session on Tools for Technical Writing 2.0.

Post tea break, Jyothi Jandhyala (BEA) presented a session on DITA migration process. Nandini Gupta (Cadence)provided insights on how to create readers by a question and answer format. While Surag Ramachandran (Honeywell) spoke on E- Learning through Gaming' and Gyaneshwar Talwar (Persistent) on 'Using FrameMaker to develop Help and PDF with a click'.

Following the presentations, Edwin Skau conducted the quiz finals. The team comprising of Gururaj BS, Jyothi and Anuradha came as winners while the team from Huawei were the runners.

Following up with a delicious lunch, the participants were treated with some more presentations- Technical Documentation in Blogging by Dr.Manjula Kandula (Sun), Sankara Rajanala (CISCO) on Technical Editiors Job. Titas Negi and Sumita Mukherjee (Symantec) provided insights into Rubicon-an XQuery based framework for intelligent help systems.

The session concluded with a vote of thanks by Fred Menezes.

Amidst all this knowledge sharing, the conference was a hub for various companies to set up their respective stalls not only to share their company awareness but also to solicit feedback from the delegates. In addition, there were contests organized and hordes of prizes given. The 9th STC regional conference at Goa proved to be a showcase of knowledge sharing and diversifying technical communication knowledge to all the quarters.

Makarand Pandit and Rajeev Jain's Technical Writing Session for Bangalore Meetup

The Bangalore Technical Writers Meetup-Supported by STC India was held at Continuos Computing, on Saturday 29th September, 2007.

The name of the attendees' and their respective companies are listed below:

1.Rajeev Jain – Zilog
2.Makarand Pandit- Technowrites
3.Ganesh Shenoy- Huawei
4.Anindita Basu- Integra Micro Systems
5.Sairam Y- LSI
6.Blessy Thomas- Citec
7.Joy Myalil- TCS
8.L Chelladurai- ABB
9.Binamra Sharma- Student
10.Rishi Malik- ACS
11.Manoj Kumar-ACS
12.Vinay Kumar- Consultant
13.Sudha A- Technowrites
14.Swetha- Truimph India
15.Gautam Goswami-ACS
16.Sreeraj- Wipro
17.Sreejith G.S- Collabis India
18.AV Jayanthil- Rebaca
19.R.Saravanan-
20.Sagar Kirloskar- Technowrites
21.Jyotsna- Zilog
22.Hemanth- TCS
23.Harihara Subramaniam- Novell
24.Swarna- PGSL
25.Naveen Cruz-Continuos Computing
26.Rajdeep Gupta- Infosys

Highlights:

The session on C++ began at 10:40 am. Rajdeep triggered the meeting by welcoming the attendees and the speakers-Rajeev Jain and Makarand Pandit. There were two sessions lined up for the day- "Programming Concepts for Writers on C++" by Rajeev Jain, Zilog and "Introduction to Structured Writing & Structured FrameMaker" by Makarand Pandit, Technowrites



Rajeev started the session by asking the attendees, what made them to attend the programming session.Rajeev started his presentation by stating "Concepts are important, not language." He then explained the basics of C++ that is, differences between a parameter and a variable, data types, input values; return values, error codes, and host of other things. He then differentiated between keywords and pre-defined identifiers. Rajeev mainly concentrated on the API/ SDK documentation.

He also provided an API template, which is the first step towards API Reference Guide documentation. He answered all the queries related to API documentation.

The training material is available at the following link:

http://techwriter.meetup.com/2/files

A break of 15 minutes was taken after which the session on "Structured Writing & Structured FrameMaker" begun. Makarand Pandit or Mak, as he is fondly called entertained the audience right from the word, GO. He quizzed the audience by questioning on authoring and documents. The answers provided the audience were up to the level. He then explained in detail the terms and cleared all their doubts.

Mak then went ahead with his illustration on Adobe FrameMaker 8.0. He explained in detail what he had learnt in 12 hours to the audience in just about one and half hours. Mak explained what Element Definition Document (EDD) and Document Type Definition (DTD) are all about. He also showed how to edit an EDD, importing a DTD, and all the other tricks that will come handy to the naïve user of FrameMaker 8.0.

Then came the Q & A time in which Mak was asked questions on all the recent developments in Information Development field. One such question was on DITA.

He then explained in brief, what DITA is all about and how it has evolved over the years.

Rajdeep concluded the session by offering a vote of thanks to Mr. Rajeev Jain and Mr. Makarand Pandit for their wonderful presentations and to Continuous Computing for sponsoring the meetup.

You can view the photos of the meetup by clicking the following URL:

http://techwriter.meetup.com/2/photos/?photoAlbumId=225090

From Word to FrameMaker with Love- Written by Mumpy

Folks

This is a piece written by Mumpy, one of Israel's most humorous technical writers. Interestingly, he makes a point on the the impact of his documentation work while migrating from Word to FrameMaker. Fantastic stuff! All credits to the writer Mumpy.

From Word to FrameMaker with Love

I decided to join the 21st century a few months ago and bought myself a brand new sparkling license for FrameMaker, complete with a Multiple Undo feature for writers like me who always realize they have made a terrible mistake just a nanosecond too late.

It was glorious waving goodbye to Word. No longer will I have to wonder why my documents go straight from page 1 to page 3. No longer will Tahoma font continue to defy me and creep into my documents unbidden. Yes, indeed, we bid a fond adieu to Word and strode confidently into the wonderful world of FrameMaker without looking back. (I did have a third technical writer who looked back and I”ve been sweeping her up all week and putting her on my salad)

But it wasn’t all fun and nice cups of tea. My trusty side-kick found it very hard to say goodbye to the little magic paintbrush icon that that you waved three times and then you could trick Word into doing what you wanted. And I simply cannot figure out how to apply shading to a middle row in a table. But by and large we are getting to grips with the table designers and the paragraph designers and the character designers and the fashion designers.

There is also all the new lingo to learn. Suddenly, we have strange and mysterious concepts like straddling and shrink wrapping, not to mention anchored frames and variables and master pages and side heads.

You know, you spend your life happily merging cells and then one day, poof, all of a sudden you have to straddle. Luckily for me, I did two years of Pilates and am quite good at straddling. Every time I get some disconcordant cells in a table and I need to straddle then, I simply lay down some towels on the floor and Bob’s your uncle

I’m even getting to grips with a Wingding Variable in a fetching shade of turquoise. And did I mention how much I like Master Pages? I’m not so keen on the Reference Pages though and I’m not quite sure what the reason is for their existence. Only God and Shlomo Perets know, and I’m not so sure about God.

The biggest problem is the time it takes to migrate from Word to FM – especially when transferring graphics. My boss is convinced that either I don’t know what I’m doing or that FrameMaker was a waste of money. I suspect that the truth, as always, lies somewhere in the middle. And now, if you will excuse me, I have about 59 unresolved cross-references to take care of. They look and act pretty resolved to me – but FM says not. And who am I to argue?

Videos of Bangalore Meetup at Proteans Software

It can now be viewed by going directly to this link:

Minutes of the Bangalore Technical Writers Meetup for July '07

The Bangalore Technical Writers meet up-supported by STC India for this month was held at Proteans Software Solutions Pvt. Ltd, on Saturday 21st July 21, 2007. The topic for the discussion was “Theories of English Grammar for Technical Writers”. Anil Pinto, Lecturer in Communication and Media Theory, Christ College, Bangalore discussed with us on this topic.

Anyway, the name of the attendees' and their respective companies are listed below:

1. Anil Pinto – Christ College
2. K Sassendran- Proteans
3. Radhika Nair -Novell
4. Anindita Basu- Integra Micro Systems
5. Cresilla Lobo- Robert Bosch
6. Blessy Thomas- Citec
7. Vandana Rao- Alcatel-Lucent
8. Sinduja R- Honeywell
9. Manjunath- Truimph India
10.Saiprabha- SAP Labs
11.Nethravathi - C4C
12.Aaron R- Wipro
13.Binu PV-Lauteb Information
14.Jaimon Mathew- IGS
15.Sreejesh-EDS
16.Rajeeva B.C- NA
17.Sreejith G.S- Collabis India
18.Vinay Kumar- Consultant
19.Sunita S- Wipro
20.Chaitrao M- G4S Training Centre
21.Reena Lasrado- G4S Training Centre
22.Suchitra- Proteans
23.Rashmi Hebbur- Journalist
24.Banurekha Balaji- Honeywell
25.Jothi- NA
26.R.S.Raju- Adroit
27.Jayant Gandhi-
28.Rajdeep Gupta- Infosys

Highlights:

The meeting started at 11.15, by a quick round of informal introduction. The most interesting point about this session was that the attendees were from various working background that cut across different domains- from Film Making to Economics.

Rajdeep triggered the meeting by welcoming the attendees and the speaker Anil Pinto. Anil kicked of the interactive session by handing over the worksheet to the attendees. The participants were asked to fill in the quiz on “what is Grammar” and “What are the theories of grammar” followed by a discussion on the different answers that the participants came up with.

Anil could easily set off a great interest among the participants to listen to and actively debate on. He discussed the following Grammar theories: Traditional, Structural Transformational-generic.

Traditional theories can be tracked back to 18th century, wherein Orthography, Etymology, Syntax, Prosody, Composition, Spelling, Pronunciation, Sentence Analysis etc were the major focus of study. The Renaissance movement- a cultural rebirth from the 14th through the middle of the 17th centuries in Europe forced the English to think beyond Latin for the style and structure of their language.


The major issue with the Traditional theory was that no two languages have the same grammar. Every language has its own inherent difference. Wren & Martin’s Grammar is one of the best examples that follows traditional grammar theories that focused mainly on words, rather than sentence or language as a whole.

Wren & Martin’s grammar book follows Shakespeare style of English, which is not applicable in many domains such as Technical Writing (though this domain was not evolved in those days; Anil just gave an example).



In response to these issues, a Structuralist theory has been evolved. When Traditional theory concentrated on words, Structuralist theory mainly looked at language as a group of different sentences. People like Saussure researched on 'Signs'. He considered language as signs. Leonard Bloomfield’s language (1933) is a book that refers to structuralist theories. Structuralist theory attempted to understand the grammar of the sentence rather than
grammar of words and its alignment in the sentence.

Noam Chomsky is one of the apostles of the Transformational-generic theory which advocated the importance of language. Anil walked the attendees though the difference between the Surface structure and Deep structure of language, and he also gave a glimpse on present universal grammar.

After the presentation, it was the exercise session that triggered debate among the participant on subject-verb disagreement. The discussion took to different levels, where Anil and the participants discussed about the bridge between academia and the Industry. One of the attendees has the opinion that the industry really does not favour the intake of trainees due to the confidentiality of the project. Everybody agreed upon the need of a curriculum for Technical Writing. Again, Regularity, syllabus and dedicated faculty are the major roadblocks to the aforementioned.

Rajdeep sought feedback from the participants about the venue for conducting future meetups. He also encouraged the Participants to volunteer their time and efforts in sustaining the activities of this group by giving presentations or seminars. Rajdeep also briefed about the upcoming STC-India Career Day and Annual Conference.

You can download the presentation from the following URL : http://techwriter.meetup.com/2/files/

Also, view the meetup photos from the following URL:
http://techwriter.meetup.com/2/photos/?photoAlbumId=190364&photoId=1767636&op=defaultAlbum

The particpants felt that Anil has kindled enough interest in them to delve deeper into the subject. We look forward to another session from Anil where we can learn about how words relate to, and play with each other.

Minutes of the Bangalore Technical Writers Meetup ((June '07)- Supported by STC India

The Bangalore Technical Writers Meetup for June '07-Supported by STC India took place in Adobe Systems on June 23rd, 2007. Listed are the attendees along with their respective companies' names:
1. Preran- ADOBE
2. Darshin Naidu- HSB Technologies
3. Anindita Basu- Integra Microsystems
4. Arun Martin- Bally Technologies
5. Bibhudatta Mohapatra- Intergra
6. D.Hemadri- Sun Microsystems
7. Joy M J- TCS
8. S.Gopal- Consultant
9. Benazir Hussain- Metalearn Services
10.Rishi Rajpal-Metalearn Services
11.G Raghu-Metalearn Services
12.Shabith Prabhakar-Metalearn Services
13.Ajit Kumar-Metalearn Services
14.K Anantha Raman-Metalearn Services
15.Rajlakshmi Borthakur-Infosys
16.Aunindra Sinha- Infosys
17.Vidya Lakshmi-
18.Shwetha Shashidharan- SAP Labs
19.Dhanish P Bhaskar- Fomax
20.Ramesh-GE
21.Pradeep L.N- Metalearn Services
22.Prabhat Ramesh- Four-C
23.Gururaj BS-ADOBE
24.Surag R- Honewell
25.Jilna Surag- Freelancher
26.Shashi Prabha- TCS
27.Banurekha Balaji- Honeywell
28.Blessy Thomas- Citec
29.Vikash Kumar- Cognizant
30.Saseendran K- Proteans
31.Manoj Potdar-Proteans
32.L.Chelladurai- ABB Global Services Ltd
33.Sreeram MV-ADOBE
34.Rajdeep Gupta-Infosys

The meetup started at 10.35 am and the agenda was "Developing interactive content". After a quick round of introduction by everyone, Rajdeep requested the speaker Preran to initate the discussion.

• Preran who has 7 years experience in Technical Communication and Web Design, started off with an introduction explaining-Learning, Various types of Learners, Interactive Learning for Simulation etc.

• After that Preran discussed Adobe Captivate's TM features like adding interactive tools e.g. text box, mouseclock. He showed how to record presentations (for example, a demo), and explained the multiple output formats for publishing.

• Preran also showed us how to create a quiz question, and the various quiz types that can be created using quiz templates for assessing user at the end of any training presentation.

• After that, Sreeram M V, Product Manager for Adobe Captivate interacted with participants on the Captivate usage. He responded to the user's queries related to Captivate, which they face during projects. The discussion was lively with users providing feedback on the Captivate tool. The participants also tried to clarify questions posed by each other.

The session concluded at around 1 pm with some informal one-one interactions.

Click here to view the photos http://techwriter.meetup.com/2/photos/?photoAlbumId=177937&photoId=1602283

Also, the meetup presentation is available for downloading at http://techwriter.meetup.com/2/files/

Interwoven Session on June 16, 2007

I had the privilege to attend the STC Learning Session on Usability conducted at Interwoven (June 16, 2007), and am sharing the session’ gist with you.

The first speaker was Sherrill Packebush, a User Experience Analyst with Interwoven who delivered a presentation on HCI and Tech Communication. She gave a basic idea of what HCI is, responsibilities and the role of tech communicators in designing.

Sherill said HCI does a lot of research on the designing and development activities. She also shared her experiences in creating wireframes, prototypes and all. In addition, She highlighted some case studies on usability namely on Amazon. com, move.com and staples.com.

She pointed out that one of the distinguished companies had to shell out $ 900, 000 on Usability issues for they ended up doing the test on the engineering team and never thought of performing it on end-users. Finally, she discussed some usability problems that are been encountered frequently.

Next was Suman Kumar, writer with DELL who delivered a session on Contingency Design, its importance and writers role in it. Citing examples, Suman said that Error messages should be treated as educating the customers. He also cited some practical examples wherein vague error messages have proved costly to the flagships of the product.

In addition, Suman thought that the following points in mind while writing error messages. Error Messages need to be identifiable, accurate, understandable, succinct, correct measure and explain what went wrong. According to Suman, writers are the perfect customer advocates and should play key roles in getting the customer requirements picture clearer to the design and development team. In a nutshell, always try to be on the user's shoes when writing error messages.

The session concluded with a Q & A.

Points on Documentation Survey

Hi Francis,

At the outset, an excellent chance to do something new out here!

Though I ain't in a position to disclose the Questionnaire (client policies and all), I will share my experiences. I had a chance of revamping the entire documentation for a particular XYZ client.
The first thing is that while I understand you are potboling with enthusiasm to be creative and come out with a new structure, please do not be in a hurry. If time permits, do an analysis of the existing manual; list out all the documentation issues in an excel sheet and try to figure out the possible alternatives to it.

Now, when you are done with that, try to chalk out in a piece of paper as what is MISSING in the document? If possible, have a coffee talk to your fellow mates, clients and end-users (if possible). If not, never mind. I suggest you to look into the customer support emails.

I am sure, there are documentation issues, which might be relevant in terms of language, structure etc of the document. Take this factors into consideration before you start with your new draft.

Create a list comprising of three sections- Major, Minor and Critical and correspondingly departments under which it should go. If there are technical documentation inaccuracy, which is major, the issue should be sorted out by the documentation team, in that case it is you.

If there are incorrect steps documented, which may lead to a wrong action on the part of the user-say an installation step, the issue is critical. If there is some mismatch with the GUI buttons failing to work and all, you need to get in touch with the development or design group. At the end, try to look out possible alternatives and come out with a solution and resolve the matter.

Try to also conduct out a test in the team itself of how users read the documentation. You will get a good idea of the readability of the documentation.

I don't know, but you can perhaps look to explain the features in a new manner-- how about creating a demo, identifying the unique features of the product.Also add a few quzzies in the note and provide feedback in the form of correct or incorrect messages. Always try to get the users in action.

My two cents
Regards Rajdeep


---------[ Received Mail Content ]----------
Subject : [twin] Documentation surveys
Date : Tue, 22 May 2007 19:06:30 +0530
From : "Francis Anthony"

Hi:

I'm starting out on a new documentation project whose content needs to be completely overhauled. I figured that the best way to go about overhauling existing documentation would be to understand:


* What is it that users found lacking in the status quo, and
* What is it that users would like to see in the revamped
documentation


To this end, I will be conducting a scientific survey of the documentation. Has any one undertaken a similar effort previously? If so, I'm interested in hearing from them about their experiences. Broad tips on how they went about it, how much time was spent in the effort,
what kind of questions formed part of the questionnaire, etc. would be greatly helpful.

Please feel free to write to me and to the group, if you like, to share your experiences and insights.



Any and all information would be much appreciated.


Many thanks,
Francis

Staright from the Organizer's Desk!

I came, I saw, and I conquered - I would like to use the axiom of Julius Caesar, to describe the Bangalore Tech Writers Meetup Group Let me take a breath here! Phew, wasn't I nervous, when Saravanan Manoharan (aka Sara) made me the Assistant Organizer of the Bangalore Meetup .

I still recall that day, when Sara called me over and said, "You are taking it over from here." Initially, I was amused as to why he chose me out of the whole bunch of seasoned technical writers in Bangalore?

But, then Sara patted me on the back, and felt that I could deliver. Well, I don't know, if I have lived up to his expectations (and those of Bangalore Tech Writers), but I can only say that, "I am trying my level best."

To be completely honest with you, it hasn't really been a smooth sailing. I have been blasted quite often, off the list by quite a few members; they were of the opinion that the agendas were offbeat and the venues were improper. I would like to use this platform to respond to some of those remarks. Please note, that in no way am I trying to incite a flame here. I am doing this with a good intention.

As far as I could make out, offbeat topics would be categorized as those topics which do not have any direct co-relation with technical writing. Here, I'd like to point that the Agenda for the meetup include topics that are selected by a panel of technical writers, including yours truly.

Over the last year, we had meetup agendas ranging from a wide range of topics such as, "Reviewing and standards", "Ways/ Methods of continuous learning for Technical Writers", "Procedure/ Steps i nvolved in planning and preparing a Users Manual for a product" to the recently concluded "How to catch errors once you freeze docs?" etc.

How many of you think these are offbeat topics? Does it not help you with your (technical) writing? I guess, what my fellow mates meant was that we should conduct technical writing sessions, in which they will have tools-related questions and all. Nothing wrong in that!

We also have had agendas on topics related to Tools (In the past, we had an agenda titled, "MS Word vs Framemaker"), but in a different atmosphere for sure - we don't encourage the use of boards, fancy conference rooms, or even a pen/ pencil. We chose to be a little different, guess there's no harm in that, right?

My point, here, is that we are not using this Meetup group to conduct learning sessions; we are just discussing an agenda informally and learning simultaneously. Our soul objective (and mind you, its 100% voluntary) is to work out solutions that one faces in day-to-day life and encourage everyone to do their bit for enhancing Technical Communication.

Few people who have turned up for such meetups have been pretty supportive in giving their feedback, and this in turn has done us a world of good. A few drops of water can make a mighty ocean. There's another issue facing us, as an entity - choosing the right venue of course. Writers who have attended the meetup complained about the venue - noisy and loud music.

While I understand and take the comments with a bowed head, I would also like to say something here. We usually have such meetups at a Coffee house or a Restaurant; to conduct a meetup in one of these places requires financial assistance. As of now, the meetup is a voluntary group. Hence, I cannot organize it in a Hotel or in a Conference Hall. I am talking to various people and orgs to organize such meetups at their premises (office rooms) for an hour or so, but its not easy to convince them.

Also, it defeats the purpose to have an informal meetup - the basis on which the meetup idea was born. We would like to keep as it as informal as possible. My request to fellow writers is -> Please have some patience and I am sure, we will work out something. But, it's not been harsh always. We have been able to do a few things quite uniquely, if I can say so.

To start with, we had some recruitment/ HR personnel joining us regularly. It gives me immense pleasure to inform all of you that some participants from the meetup have secured jobs as well by networking. In addition, there have been certain representatives from technical writing institutes, who have got students enrolled. Good news, isn't it?

As we approach another year, I would like to seek an active hand from all of you. To start with, I would like to know what sort of discussions can we have in such meetups, time and venue you would like to suggest? Do you like to have meetups where we make effective use of a whiteboard? Please feel free to voice your opinion offlist to me. My email address is < > My gratitude to Saravanan Manoharan for his constant support and feedback.

Just like another Technical Writer, I am also trying to learn the intricacies of technical writing and group meetings like the Bangalore Meetup has surely given me the confidence and knowledge to go a long way. It may be true for some more writers like me.

I am sure the coming year brings a lot of happiness in each and everyone's life. I urge my fellow writers in Bangalore to extend a hand to my meetup efforts, so that we can help ourselves to be worthy Documentors.

I know TIME is a real factor here, and weekends is the only time when everyone wants to windup, but trust me if you can contribute a little time of yours in such meetups, it definitely adds value to you writing. Finally, I look forward to receiving mails from all quarters about the Meetup. Thanks for your cooperation! Let's make the Bangalore Meetup the best of its kind. Cheers! Rajdeep

API Session with Rajeev Jain

Technical Writers April Meetup

Agenda: Documenting your first API.

Attendes: 17

The attendees' names along with their respective companies name are listed below:
1. Rajeev Jain - Zilog
2. Lakshmi RS - Gemini Software Solutions
3. Reuben - Arcot
4. Shashi Prabha - TCS
5. Sumit Kumar - Lucent
6. Naveen Chandra - Cokinetic
7. Harish BS - Keeline India Ltd
8. Abhilash Scariya - SAP Labs
9. Imran Ulla - First Indian Corp
10.S Gopal - Goodwill Technologies
11.Priyadarshini Narendran- Zilog
12.Mamata - Arcot
13.Jainthi Sasikumar - Argos Soft
14.Shoba Shanker - Citec
15.Anitha Sadashiv - Technopoint
16.Vishalakshi - Technopoint
17.Rajdeep Gupta – Infosys

Highlights: The session began at 10.30 am. After a formal round of introduction of participants by Rajdeep, Mr. Rajeev Jain started the presentation. It was quite an enthusiastic and interactive session.

Mr. Rajeev Jain started the session by explaining the basics of programming (sequence, selection and iteration). He said that if one understood the programming basics, documenting API was not difficult. Later he spoke on basics of API writing and how different was API documentation from GUI documentation. The do’s and dont’s while documenting APIs were also discussed.

The entire discussion was made easy to follow by providing apt examples of C++ APIs.

Clearing the doubt of one of the participants, Mr. Rajeev said that APIs could be classified into two-Internal APIs and External APIs. Usually, it is the external/exposed/customer facing APIs that are documented.

Answering another question as to what all should be included in the API documentation, Mr Rajeev said that the API document was like a dictionary to the programmer, which was never read from cover to cover, but referenced on an ad hoc basis. He also provided with a sample API document template, and explained the various headings and the reason for the particular heading order.

The meeting concluded with idea that API documentation was very easy, provided one knew the basics of programming and that, API documentation is also a lucrative career option.

The writers attending the meetup found it very informative and useful. Those who were in API documentation got a better idea of what to do, and the rest got an idea of what API documentation was all about.

A few attendees expressed their desire to be regular in meetup.

Mr. Rajdeep concluded the session by offering a vote of thanks to Mr. Rajeev Jain for delivering a wonderful presentation and to Technopoint for sponsoring the meetup.

You can view the meetup photos by clicking the following URL
http://techwriter.meetup.com/2/photos/?photoAlbumId=156076&photoId=1336004

The presentation will also be available at the Meetup website ; you can get in touch with Rajdeep for further details.