All about Technical Documentation

1. Are you curious to know about technical documentation?
2. Are you planning to begin your career in TW area?
3. Do you have any plans in changing lanes from your development or academic field to TW area?

If the answer is YES for all the above questions, then you must check this website.  In this site, you can find some basic know-how, checklists, tools and links, which will help you to write create clear and concise user-friendly manuals, online help files, software demos, tutorials and other forms of user assistance.

There is a huge list of useful software, useful websites too. Hope you will like it.

I wish you all a happy NEW YEAR 2010 and may this year brings all happiness and prosperous in everybody’s life.

Learn English

 English is most commonly accepted language for business all over the world. (Chinese and Japanese won’t agree with my statement ). So learning English is vital for the people who are not native English speakers. There are many websites which teaches effective English. I came across one among these sites which is quite interesting.

Log-on to www.learnenglish.de where you can learn English basics, grammar, vocabulary, quizzes and games too. Moreover this site provides information on British culture, common mistakes in English, interesting facts, Homophones, pronunciations, dictations and a lot in their stocks. Check it out once and I am sure you will love it.

All-in-One

 

Yesterday (Dec 1^st) was my Birthday (don’t ask me how many candles were there on the cake..?).  Also incidentally or accidentally yesterday was the World AIDS awareness day. Sometimes it happens. Don’t link my birthday with AIDS awareness. 

Well, I came across an interesting info which I wanted to share it with you in this space. You may know very well how much time you need to install new applications (of course, one by one) in your new or formatted system/laptop. You may need many free installable like Web browser, messenger service, Flash Player, Word-to-PDF, Image capturing/editing tools and to name a few in your laptop forever.

http://ninite.com has come up with a solution for the above problem I mentioned. Here we go:

1. Go to http://ninite.com
2. Select your required or favourite applications  
3. Click the Install button and enjoy a cricket match or a cup of tea with your friends.

Select the applications from the ninite

Sounds simple, is itn’t..?

New Features in Captivate 4

As I mentioned in my earlier post on Captivate, I always enjoy using Captivate and admire its user-friendly features. Adobe has released Captivate 4 recently.

Here is the list of my favourite features:

• Panning While Recording
• Widgets
• Project and Design Templates
• Table of Contents
• Single or Multiple SWF Output
• Text-to-speech Captions
• Captivate Reviewer
• Photoshop Layer Support

To read a detailed review on Captivate 4, read Scott DeLoach’s article in http://writerua.com.

The most bothering drawback is Captivate 4 help system is not context-sensitive.

Technical Writer’s Role in UI Design

 

User Interface (UI) designing is no longer been a developers cup of tea nowadays. In most cases, it is the Technical Writer who becomes the first person to explore an application/product. As a result, a TW will be in a better person to tell his UI experience with the application/product in user point of view.

Being an individual contributor in my company, besides technical authoring, I almost wear multiple hats:

• UI Design Advisor
• Beta Tester
• Product Trainer for the Beginners/Fresher.

Recently, I happen to test one application. Surprisingly, I was not a part of the team in the UI designing phase. An UI designer inside me came out while testing that application. Besides functionality testing, I started listing down UI design suggestions (Please note that they are only suggestions not advice). Look out the below image which bothered me a lot.

Bad UI Design

What is the necessity of placing a Close button below the Close icon already available by default..?

To be honest, for me it doesn’t makes any sense. Any UI should be designed keeping the User in mind no matter he is an advance or novice user. UI design should be in such a way that it should guide the user to explore the product without making him to press F1 often. You need not to design a colourful UI but definitely not a clumsy something like this:

Complex UI Design

      (Picture courtesy: Tom Johnson’s http://Idratherbewriting.com)

Things to do before using the Captivate

 I always rely on Adobe Captivate (before it was Macromedia Captivate) for preparing training materials, tutorials and demos. It is simple to handle as well as effective in covering your clients training needs. Not only you can customize the call-outs and standard messages, but also it gives a real effect of exploring your product/application.

There are few pre-requisites before you start on with captivate.

Close your Outlook and Instant messenger services without any second thought. Whenever you get a new email, outlook will show a pop-pop alert. Captivate will capture those pop-ups also along with your regular actions in the application. So as a result, your client will come to know that your mailbox has exceeded its limit through your training demo.

Captivate captures your Outlook pop-ups

Never open or explore any applications, folders when you are capturing with the Captivate. Reason is same as mentioned above. Otherwise be ready to redo your capture. 

Working with Bookmarks in Adobe PDFs

 Recently, the same friend raised one interesting query. It looked very simple. Here we go:

I have included chapter names, heading level 1, level 2 and so on as book marks in a FrameMaker book and generated a PDF. When I open that PDF for the first time, I would like to see only chapter names as bookmarks not all the heading levels expanded. Should I do something with FrameMaker settings..? This was her query.  

                                    Expected:

Only Chapters as Bookmark

                                    Actual:

chapters Expanded

As per my knowledge, FrameMaker has nothing to do with this query, it’s the Acrobat Professional that you need to do with some settings change while opening the PDF.  (As I don’t have a copy of Adobe professional, I was not able to mention the exact menu to change the settings.)

Later she got the exact answer from www.allexperts.com posted by Mr. Wayne. Here is the exact saying:

“If you “Open” the document in Adobe Professional – and you are using Adobe 6.0 or higher. You might look under the preferences screen and see if there might be a setting that says something like – “remember last” and check or uncheck the box depending on how the text is worded.

You might also just try opening the document in Adobe Professional – and then “collapse” all the bookmarks then save the document and reopen it and see if the bookmarks stay collapsed.

Try the following: Open Distiller and then select Settings > Security and then make sure the following box is UNCHECKED – “NO CHANGING THE DOCUMENT.”

So the exact solution is:

1. Open the PDF in Adobe Professional and select Preferences
2. Select “’remember setting of last view” option.
3. Collapse all the bookmarks as you need.
4. Save the PDF and close the Adobe Professional application.
5. Open the same PDF again in the Adobe Professional.

You will find the bookmarks in same state as you needed.

It sounds so simple. Is it not..? 

Documentation – Still a least cared area…?

 

I am a frequent visitor of Tom’s space. Last week when I was reading his post on wiki, few thoughts provoked me to update my space too. There is a unanimous belief among TWs’ is that Documentation is the least cared area and hardly very few project managers concern about the documentation while releasing a product. More or less it’s a fact too.

Though TWs’ took active participation in requirement analysis, UI designing, even QA testing, still documentation is considered as a grey area. I am really curious to know what will happen if any one ships their product without any documentation (includes both online and printed manuals)..? What will be the customer’s reaction on that product..?  It may sound funny or even weird, but I mean it.

Jeff has given a reply on my above comment at Tom’s space as follows:

I just read about a product that shipped without documentation – it’s called Fitbit, and in multiple reviews the reviewers complained that they couldn’t figure out how to use it and that there was no documentation.

See http://www.engadget.com/2009/10/15/fitbit-review/   for example.

Excerpt: “…shame that wasn’t in the manual. That’s because no manual comes with the thing, the implication being you just throw it on and go to town. Again that’s not quite the reality, especially when it comes to sleep.”

Thanks for this link Jeff.

On the other side of a coin, rarely we give feedbacks in our daily life. In any websites or help sections, there is a separate comment section for customer feedback.

Do we really like to drop a line over there..?

To be honest, I admit that I hardly give feedback. So, even I am not doing any justice to documentation, how could I expect a fair justice from others..? Hope I will change gradually.

Out-Of-Office

 

Last week I sent an email to Mr. X. I got an Out-Of-Office reply from Mr.X as follows:

I am on leave (dd/mm/yy). For any urgent queries, please contact Mr.Y.

 Ok, this is fine for me because I know both Mr.X and Mr.Y and their email ids (even their mobile numbers). Imagine if someone who don’t know Mr.Y and his email id (obviously), how he/she will contact Mr.Y on urgent situations. Am I sounding correctly..?

In Office 2007, there is an Out-Of-Office assistant (tools > Out-Of-Office assistant), where you can set many rules. No, this post is not about how to enable an Out-Of-Office reply from Office 2007. I wanted to point out the communication gap happens while we communicate with others. We assume that we have communicated effectively.

So, here’s my revised O-O-O version:

Hi,

Thanks for your e-mail. I am on leave (from dd/mm/yy to dd/mm/yy). Please contact Mr.Y [e-mail id & work phone (if possible Mr.Y’s mobile also)] for any urgent queries you may have.

Hope I have covered all the information for a new user. Did I missed anything..? Comment section is always open for you.

US English or UK English

 Today when I was commuting to my office, I saw a display board hanging in a petrol station.

 What a big deal..? That Z in authorized and the word ‘centre’ draw my attention. I mean to say; those words draw a TW’s attention.

Authorized – It’s clearly an US English style

Centre – I believe, in the US, this word is spelled as ‘center’.

So a perfect mixture of (or confusion I would say) US and UK English has happened in this display board. Either it should be

“Govt authorised centre….” 

OR

“Govt authorized center….”

(Here, I haven’t pointed out the acronym Govt refers to Government).

In India, people love to ask one common question when interviewing technical writers “Are you able to write for US audience?”

I am searching for a book or journal which discuss the difference between the US and UK English standards in detail. Any suggestions..?