My new site a Ux designer coming up shortly

I will post the link once the website is ready,  please give me your feedback.

When wrtiting a title.......

A title must be simple but informative and easy to understand. A title presents the message of topic or chapter in just a few words.

• Length of the title

Keep your titles simple, short and clear. Avoid long ones.

• Avoid Abbreviations

Avoid abbreviations by writing out the full word.

• Do not use –of genitives

Right: Prime minister’s daughter

Wrong:  Daughter of the Prime minister

Right: Usage hours

Wrong: Hours of usage

• Parentheses

Avoid parentheses in a title

• Do not use comma

Do not use comma in a title unless the title is a list of items.

An alternative to Adobe illustrator - Inkscape

Inkscape is an open source alternative to Adobe illustrator

 

Download it from the link below:
http://www.inkscape.org/download/


This tool allows you to import .ai files.You can edit the image and save it in .png and .emf format.

I found this interesting.

Proof reading tips

Whenever you are writing an article, an email, a manual etc, it is important to ensure that it is free of mistakes. The spell checker is good to use but is far from foolproof.  This is when proof reading comes into picture.

Below are a few tips that will make proofreading effective.

Print the document

It is a well known fact that people read differently on screen and on paper. Proof  reading works better on paper then on screen.

Avoid distraction

Since the job demands you to spot mistakes, you need to concentrate. Switch off the mobile phones, log-off from the chat, any social networking sites. For sure, silence will work wonders for this activity.

One at a time

Never try to find all mistakes at the same time.  List the mistakes that you intended  like the following

• Typos
• Missing words
• Formatting mistakes

Know the rules of the game

Some rules of the game include:

• Look out for homonyms
• Check punctuation
• Use and so on instead of etc
• Use through instead of via etc
• 1 t0 9 in figures, 10 and above in words

 Read backwards

When you read backwards you concentrate on the words and not the meaning.

Check for the number value

Ensure the number used and the place value of the numbers are correct.

A last step

Once you have finished proofreading, get another person to proofread it again. You will be amazed to see mistakes you have missed.  Ensure the mistakes are corrected.

Proof reading marks and symbols

 We have a set of certain proofreading symbols used, get familiar with it.

See the link below for the proof reading symbols

http://webster.commnet.edu/writing/symbols.htm

Publications guide and Style guide

What is a Style guide?

A style guide is a book that outlines the necessary rules a writer must follow for any kind of documentation. The rules the writer has to follow may be simple things like grammar and punctuation or something more than this like citation, layout, and format.

What is a Publication guide?

A publication guide is information set that deals with the guidelines the writer should follow to submit the project.  In a wider sense the publication guide covers the set of rules the writer should follow to complete each topic successfully and also the information on what the writer should not do on that particular topic.

A style guide is just a part of the publication guide.

What do you include in a Publication guide?

A Publication guide may include the following:

• Steps for publication planning
• Logo and icons used in writing
• Illustration guidelines
• Legal agreement and disclaimer statements
• Copyright information
• Documentation process
• Documentation tips
• Dictionaries, naming conventions, Glossary
• Template guidelines
• Help  on project back-up, project file location and so on

 Why is Publication guide required?

A Publication guide is a framework or a reference to help future contributors to accomplish the task successfully. These guidelines may help the newbie or those who or not familiar with the project.

Looking at this from the company perspective, it saves money and time of the writers as they do not have to reinvent the wheel.  A publication guide covers a wider range of documents like the newsletter, marketing publications, brochures and so on

Punch line

 A style guide is a set of stylistic guidelines of a publication and publication guide is a documentation of documentation

Software Documentation - Types of manuals/guides

Before you start writing, you must first decide on the type of manual. Each type of manual has a different set of audience, purpose and an objective.

If the reader is trying to learn the application, then you need to write a tutorial. If the user is already using the application and just wants some information, then the user is looking out for a reference manual. If the user is just upgraded the application, then the user is looking out for a release notes, to get the updates.

Documentation in a software industry can be broadly classified into two groups namely

• Process documentation
• Product documentation 

Process documentation

It is very important to manage the process for an effective management of the company. A software development process involves a lot of cognitive task rather than physical task; the only way of visibility is attained through technical documentation. Process documents include the following:

• Reports
• Mails and messages
• Standards documents
• Planning and estimation
• Scheduling

Product documentation

Product documentation is describing the delivered software product. Product documentation includes two types of documentation set namely:

• User documentation set: A set of documents which tells the user how to use the product.
• System documentation set: A set of documents to cater the needs of the maintenance engineers.

User documentation set

Users of the software product are not all the same. As technical writers we must structure the content for different tasks and expertise levels. I think it is not necessary for me to explain end user and system administrator. I will be using these terms frequently.

The user documentation set includes

• Functional Specification Document
• Installation Guide 
• Quick Start Guide 
• User Manual 
• Reference manual 
• Administration guide
• Release notes

Functional Specification Document outlines the behavior of the application. The documentation typically describes what is needed by the system user as well as requested properties of inputs and outputs. This document does not describe the internal architecture of the application. It just describes the interaction between the user and the software application.

Installation Guide is for the system administrators. It provides the complete details and the step-by-step instructions to install the application. It contains the complete list of the hardware and the software requirements to install the application. It also explains the configuration changes and the system settings to be changed prior or post installation.

Quick Start Guide aims to provide the overview of the application. It mainly explains the menus, sub-menus, and navigation option etc of the Graphical user interface (GUI)

User manual is to assist the user to use the application. It is also commonly called manual. It explains the application in a language that a non-technical user can understand.

Reference manual is for the experienced users. It describes about the features and its usage. A reference manual provides the complete list of error message and its recovery procedures.

Administration guide is for the system administrator for installing maintaining and managing the application. If hardware is involved, it explains the administrator’s task in maintaining the application.

Release note is a document distributed with software product, often when the product is still in the development or test state (e.g., a beta release). For products that have already been in use by clients, the release note is a supplementary document that is delivered to the customer when a bug is fixed or an enhancement is made to the product.

System Documentation Set

System Documentation includes all the documents right from the requirement specification to the final acceptance plan. Documents describing the design, implementation and testing of a system are essential if the program is to be understood and maintained.

Microsoft Manual of Style, 4th Edition

The 4th edition of Microsoft Manual of Style is due to be released in December 2011. See the link below

http://blogs.msdn.com/b/microsoft_press/archive/2011/10/26/sneak-peek-the-microsoft-manual-of-style-4th-edition.aspx

Throw a glance for a bird's eye view of the 2nd and 5th chapter. It's good!!

IBM Style guide

The IBM Style Guide is now available in hardcopy and as a downloadable ebook on Amazon.

http://www.amazon.com/IBM-Style-Guide-Conventions-Writers/dp/0132101300/ref=sr_1_1?ie=UTF8&qid=1319723497&sr=8-1

 

It is also available on flipkart: http://www.flipkart.com/books/0132101300?pid=mow3frnbjb&_l=CJHVEqJO3veuHytbACc9dw--&_r=FMJ56mRswTWEnB_o3x9ZWg--&ref=7cccee74-4a52-46ef-8a94-7d8b8c82fe00

Effective writing

Effective writing and the right language is the primary conductor between your brain and the minds of your audience. Good style helps to communicate ideas and information effectively.

Know your audience

The most important guideline of effective writing that I have ever seen is to know your audience.

Some people prefer presenting any information in a formal way, while some prefer it the opposite way.  But according to me, if the writing is like a speech it is more effective.

Choose words precisely.

A word shrinks the phrase or a sentence. It is easy to just use a single word instead of using a sentence or a phrase. Instead of writing “it was an uncontrolled, unpredictable, instance” we can just write it as “accident”.

Write clear and concise sentences

When you are writing avoid beating around the bush. Avoid using fillers like very, actually…etc since; these words add no value to your writing.

Organize information logically

Assemble or pile the similar information together. Check for the information flow and the sequence of the information. Do not create gaps between the information, it should be well knit.

Edit and format

Edit and format the information to improve the flow and presentation. This could sometimes be moving the whole paragraph to a different space in your project. Remove the needless and redundant information from the document.

Review

The best way to review is to read the information aloud. This is by far the best way to root out redundancies, gaps in logic or progression, and run-on sentences that looked all right on paper. Check for meaning of uncommon words and technical terms to make sure they say what you intended to convey.

What is context-sensitive help?

A help topic or a set of help topics that can be showed to the user on request is called a Context Sensitive Help. This form of help is delivered to the user usually on the click on F1 or a click on the help icon.

There are two forms of context sensitive help:

Field- Level context sensitive help

When you click on any object (button, field and so on), related information is displayed in a window or a popup. Usually the help is a short paragraph or bulleted points that explain the object.

Dialog-Level context sensitive help

A window is displayed. The help explains all the objects in the screen. A design with table of contents is usually displayed on the left hand side of the screen.

How does it work?

A help file is linked to the application using a Map ID and this is a number. The map IDs can either be supplied by the Software Developer or the Technical Writer.