Thursday, July 17, 2008

Technical Writing: What is it?

Technical writing is a type of writing that tells people how to use a product – any kind of product. Products can range from a Boeing 777 to a PDA phone. User manuals or any other technical writing output not only tells how to use a product but everything else about the product, such as why you should use the product, salient features, limitations, work around solutions, and trouble shooting information - should your Boeing 777 be nosing diving without a warning.

Technical writing output includes documents, such as User Guides, Quick Reference Manuals, and Trouble Shooting Guides. Most product documentation comes under these three categories.

So next time you are unable to add contacts to your new iPhone 3G, you might just be looking for that user manual (iPhone 3G User Manual). And yes, this user manual is a product of technical writing.

People who do technical writing are called pseudo geeks? Right? No, wrong! People who do technical writings are called technical writers or technical communicators. So to have written that iPhone user manual, a group of technical writers would have got hold of an iPhone much before any one of us did and played with the product day in and day out or at least everyday at work. Then they would have put together their observations into a document and created a list called the content outline listing all the stuff you can do using an iPhone and how to do it. For example, the iPhone manual starts with:

Chapter 1: Getting Smacked (started)

- What You Need

- Activating iPhone

- Upgrading from an Original iPhone

And so on.

So there you have it. You have products. You have writers. And when these writers create content to help you use these products, you have technical writing.

Who can become a Technical Writer?

As long as you are good teacher, have an excellent hold over the language in which you are writing, and you love technology or willing to delve into the technical abyss, you can be an effective technical writer.

To start as a technical writer, know the basics:
Communication Fundamentals
*Communication Models
*Factors affecting communication
*Verbal and non-verbal communication

Grammar
*Nuances of English Grammar
*Global English - US & UK English
*Comprehension
*Active and Passive Voices
*Gender Fair Language

Technical Writing Tools
*FrameMaker
*RoboHelp
*Epic Editor
*Quadralay webworks
*Author IT
*Captivate
*Snag It

Professional Qualifications Required for Technical Writing

Anybody with good (read excellent) written communication skill and a perennial urge to learn technology can be a success in technical writing.
Having said that, I would like to highlight that like any other specialized field, technical writing has its own set of academic specializations. Technical writers with an engineering background and good language skills are a sought after lot. However, if you have mastered your arts and know your Plato from your Aristotle, you can still make a geeky bard.

Watch this space for a lowdown on the top ten courses for technical writing and where to get them.

Wednesday, July 09, 2008

But Pappu can’t write saala!

As a documentation manager, I have had enough opportunities to interview people for technical writing positions. And to me, each of these candidates are interesting in their own ways – some are smug like a Cheshire cat, some oh so docile, and then there are others who would start interviewing you back.

Last week I interviewed this dude, yes, I call him dude with a purpose. He was dressed to kill (impress?), got this Yankee twang, and his attitude was contagious. The interview process started with a telephonic round and I must say he impressed the hell out of the HR lady. She passed him on to me. After my call with him, I was sure that we could move him to the next round where we meet candidates in person.

I asked one of my peers to have a chat with the dude and let me know what she thinks. After 15 minutes, she comes back all mighty impressed but with a rejoinder, “if this guy does well in the written test, you will never have to worry about low visibility of the tech pubs team. This guy can be an ambassador for the team and his communications skills are excellent”.

Music to my ears? Definitely! Personally, I like vivacious types and dude seemed to fit the bill in all respect. He had a great attitude, knew the nuances of tech writing, and replied positively to all the typical yada yada you ask a prospective tech writer.

So, armed with my conviction that we have a good candidate, I fixed a date and asked dude to take a writing test. Dude was a little hesitant about the test but accepted to take it anyway.

I sent out the test to our in-house editor, a person with immense experience in her job, and I had also added a foreword about how we all liked this guy. After evaluating his test papers, she sent back a detailed feedback and ended her message with the note, “whatever you say, Joy, but this Pappu can’t write saala!”

I am extremely sad because I kind of liked Pappu!

Friday, July 04, 2008

Who is a Successful Technical Writer?

I have been talking to a very senior technical writer recently. I asked her who according to her is a successful technical writer. She said, “A successful technical writer is a star in the eyes of the development team, meets quality and time parameters, and conforms to the common rules and regulations of the organization”. A star in the eyes of the development team? Would not being a star among her peers and immediate manager be a wiser prospect for a technical writer?

“No”, explained my senior writer friend. She continued, “This is because in most cases, a tech writer must have her work validated by a developer. If the developer is happy, the person might send a note of appreciation to the writer and also cc the writer’s manager. So you see the writer not only buys brownie points with the geek God, but also impresses her manager – all in one shot”.

“When a developer finds the technical writing content of high quality, he/she is left with more time to do value additions on the doc as opposed to making the document technically correct. Some time strapped developers might do no value addition, yet appreciate the writer as they could safely return the document to the writer and feel secure about the technical accuracy of the content. And when external stakeholder are happy, it bodes well for the entire techinal publication team as well and documentation managers love that.”

“And what if the writer’s work involves no interaction with the technical team?” I asked. “In that case, the writer’s work must derive a direct benefit to the company, for example, a well written proposal should help the company close deals”.

“So the idea is to attract positive feedback”, I said trying to get her right. “Exactly! The idea is not only to do things to attract positive feedback, but also convert the feedback into rewards!

“How”? I asked. She said, “Look, when you receive positive feedback from stakeholders (people who directly or indirectly benefit from your work), you can use these feedbacks to back up your ratings during appraisals. So if you have rated yourself 4/5, you can justify your ratings with the feedback you have received – simply copy and paste the feedback into the appraisal form and see them turn into raises and bonuses”.

I said, “All these sound too good and almost convincing, but how do I attract positive feedback from developers?

The lady continued, “Well to start with get down and dirty with technology”. Ask questions, even stupid dumb ones, but ask. You might receive those what-a-moron stares initially. But continue asking until you make sense of what the technology is all about. Draw the big picture and place the finer details within the picture as you go along. Work with the applications, talk technology, and buy those dummy guides if need be. Be persistent!

I interrupted, “ How do I know I am being persistent, that I am learning things”? She said, “Look out for the questions you ask. As you learn more, you will ask smarter questions, more specific questions as opposed to open-ended ones. For instance, instead of asking what is PeopleSoft HRMS is all about, you might find yourself asking how are job profiles set up in PeopleSoft HRMS?”

“So, to be a successful technical writer, I have to ask the right questions and please my developers”, I concluded. “Nope” she corrected. “To be a successful technical writer, you have to not fear technology and be always eager and hungry for more information, better still if you make up your mind to master the technology. “Hold on! I said. She was working me up too fast. “But what if I am not in a product company, but working for a project company where technology changes all the time”. She said, “Chances are that if you master .NET, for example, you will also better understand how other programming languages work, say Java, Pearl, or Cold Fusion.

So the key is not to fear technology but master it! A good technical writer should be able to replace a product manager or a developer any day. Intrigued, I continued, “And what about the other two - quality and time parameters and conformance to the common rules and regulations of the organization”. “Lets keep that for another day, Joy, I really have to rush now”. I can’t wait for that another day.

Tuesday, July 01, 2008

User Productivity Kit (UPK)

Oracle’s User Productivity Kit (UPK) is a multifaceted eLearning tool that can be used to record steps and play back the steps in exact sequence in various interactive modes, such as See It Mode, Try It Mode, Know It Mode, and Do It Mode.

What makes UPK unique, compared to other screen capture tools (Viewlet Builder, Captivate) is its ability to display appropriate text, such as menu and menu item names captured during the recording.

For example, if you set up UPK to work with MS Word, and you want to record the steps to print a file, then UPK will not only capture steps to print but also display in text the menu, menu items, and window names involved in printing the file.

So to print a document, you would go to File menu, select Print, choose a printer name in the Print dialog box, and click OK. When you use UPK to capture this series of steps, UPK will record the sequence of events and display the following text messages in bubble boxes:

1. Start by navigating to the File Menu.
2. Select Print.
3. Click the Name drop down list.
4. Select Printer 1.
5. Click OK.

Because UPK automatically inserts textual content, it minimizes chances of edit errors and increases productivity by allowing you to record several tasks within a short period. UPK also allows you to edit your recordings if you have missed a step or captured a wrong step.

To know more about UPK, go to:
http://www.oracle.com/applications/tutor/user-productivity-kit.html

To have your common UPK issues answered, visit:\http://www.oracle.com/applications/tutor/upk-faq.pdf

Resolving PDF Problems!

You need to send that PDF file by close of business to your product manager/SME and the file won't just print. What do you do?

Listed here is a set of common PDF issues and solutions:

Pain: When you right-click a Microsoft Office file to convert to Adobe PDF, the application returns the message, "Missing PDFMaker files," and does not create an Adobe PDF file.

Solution: Remove Adobe PDF from the Disabled Items list in the Microsoft Office application.
To manage your Disabled Items list in a Microsoft Office application:
1. Open the Microsoft Office application (Word, Excel, Publisher).
2. Choose Help > About [the application name].
3. Click Disabled Items.
4. Select Adobe PDF from the list, and clickEnable.
5. Quit the Microsoft Office application, and then restart it.

If the error message continues to appear after you enable Adobe PDF, then check the security level for macros in Word:
1. Choose Tools > Macro > Security.
2. In the Security dialog, click the Security tab.
3. Choose Medium or High.
4. Do one of the following:
-- If you chose Medium, then click OK.
-- If you chose High, then continue with steps 5 through 7.
5. Click the Trusted Publishers tab.
6. Check Trust all installed add-ins and templates.
7. Click OK.

PDFMaker and the right-click context menu should function again.

For more, see http://kb.adobe.com/selfservice/microsites/microsite.do

Pain: Images look fine in MS Word, but after converting to PDF, image quality is poor.

Solution: Save your image in JPG or TIFF format and embed the image into your Word document to publish using Adobe PDF printer. PNGs are not suitable for word to PDF conversion, TIFFS work much better. Use high quality print setting while converting to PDF. Also, standardize the resolution settings of your desktop (1024*768) and the DPI setting in your screen capture software.


Watch this space for more!

IBN Top Headlines

Ads

Search the Web:

Need more targeted traffic?
Join TrafficSwarm for FREE!