Best Practice on Documentation

INDEX
Common Errors Documentation Tips
Know Your Audience Plain English and Simple statements Bullet points or List

Premium Documents TCS TechCom

Common Mistakes
Skipping the Glossary Not being suitably graphic Poor Spelling Future Tense Using an Advanced Vocabulary Forgetting ones audience Poor Ordering Old Data

 Know Your Audience

Imagine how your reader might experience your communication. Convincing? Plainly informative? Difficult? (Domain of your audience, )

Use Plain English and Simple statements

(To reduce ambiguity To translate text cost-effectively To reduce customer complaints and legal liability )

Prefer Bullet points & List

Know Your Audience

Questions Who are the users of the document? Generic Identify the intended audience or user group of the document. SPEED-Specific Be clear that users will include all permanent TCS associates, who are graduates, computer-literate and have a basic understanding of the TCS appraisal process. Understand that users will use the manual to perform all appraisal-related tasks without a hitch.

Why should the users read the document?

Provide the purpose of the document.

What do they need to know? What content should the document include?

Identify the relevant content to be included in the document, based on the users and purpose (the who and why).
Define situations and the context for the document. Plan the structure of the document, such that users can find topics easily. Indicate the location/availability of the document, based on where the user is most likely to look for it.

Define the scope to include all appraisalrelated tasks to be performed and howto perform the tasks.

When will users read the document? How should the document be organized?

Consider all scenarios when users will use the document agreement vs. disagreement with goals, appraisal, rating Organize the document based on user-roles and/or the appraisal process flow. Then arrange task topics accordingly. Inform users about the location of the document, and encourage them to read it before they begin the appraisal.

Where will users find the document online or offline?

Plain English / Simple Statements

Original Simplified

The consequence of user action is conveyed through a message visible on the screen.
It may be fatal if this equipment is contacted by non-professionals. The Product status code will be visible but the fields will have no data input. The firewall is a key-upgradable integrated security mechanism. Optivity NMS addressed this problem via a software fix that was made available in early Q1 FY09.

An alert message is displayed on the screen.

Do not touch this equipment, if you are not trained. The Product Status code is a read-only field. You cannot edit this data. The firewall is a security device that can be upgraded by a license key. A software patch for the ONMS was issued in April 2009.

Its Intelligent Layered Security architecture delivers multiple layers of protection that work together to detect and block threats from attacking your network.

The device has different layers of protection that detect and prevent damage to the network.

Bullet points or List

Type of List
Numbered list

Guideline
Use a numbered list for items that are in sequential order.

Example
To create a new e-mail ID: 1. Click the New Entries tab. 2. Enter an ID for the mail address. 3. Click Save.

Bulleted list

Use a bulleted list for items that require highlighting but do not imply any order of sequence or importance.

This document is meant for the following audience:

Subject Matter Experts (SMEs) Core Team Project Leads from TCS

Inset heading list

This is a vertical list with headings inset at the beginning of the items. It is useful for indicating the contents of each item in a lengthy vertical list.

TCS conducts its business through a variety of communication channels. E-mail: Written medium that can be stored, referenced and circulated. Teleconference: It may be less frequent than email or one-on-one telephone calls.

Two-column list

Use a two-column list when you have a series of paired items.

Given below are definitions of terms used in this procedure manual. TCC SME DRT TechCom Coordinator Subject Matter Expert Document Review Tool

Example
Ever read a user's guide that looked like a collection of essays?

Take a look at this procedure.

"In order to access XYZ application, you need to open Microsoft Internet Explorer. You can use the address bar to access the application. You will be required to type in the URL http://www.xyz.in of the application in the address field of the explorer to take you to the desired location. You will reach the welcome window. After entering the user details in the application, the login button must be clicked by you. Then you can enter your user name and password in the displayed fields."

Now, look at a structured form of this procedure. To log on to XYZ application:

1. Open Microsoft Internet Explorer. 2. Type http://www.xyz.in in the Address field. The Welcome window appears. 3. Enter your user name and password. 4. Click Login.

Premium Documents
Client Deliverable Requirements Document Internal Documents
Process Documentation
Induction Manual, Project Process, Recurring Activities

Implementation Proposal
Design Document Operational Documents

System Documentation
Architecture/Landscape Document Log of changes (Details/ Cause of change)

Test Cases
Help Manual Run Book

User Guide / Manual/ Training Document Issue Resolution Document Document Inventory

 Thank You