Language Expertise
Read this –
When the sum of error count and flag count is less than 5% of the total number of records the valid data is imported into the database after truncating the preexisting data in the table i.e. the transaction is committed and a record of the errors is maintained.
Isn’t this difficult to understand? Can we rephrase this as given below?
When the sum of error count and flag count is less than 5% of the total number of records, the valid data is imported into the database. The previously existing data in the table is truncated before the import. The transaction is committed and a record of errors is maintained.
We broke the original 49-word sentence up into three relatively small sentences to make it more understandable.
Language is the most powerful tool of communication. Appropriate use of the language not only conveys what you mean to say but it leaves good impression on the audiences’ minds. In written technical communication, using correct and simple language is imperative. Using figurative or ornamental language is a strict no-no since the very purpose of writing documents is to get the message across. But can we tolerate ‘Both of you three, get lost’ or ‘Open the window and the let the climate/environment/atmosphere come in’ or ‘Do not use commas which aren’t necessary’ or ‘Do not obfuscate your writing with extraneous verbiage’ ? NO. Writing is the simplest art form and the most difficult too when you decide to write something.
Write your first draft with your heart. Re-write with your head.
Fall in love with your document first and then write it as if you are writing a love letter of course sans the decorative language you would use to woo and appreciate your beloved.
Wear the user’s cap before you start writing. Think from the user’s perspective. For example, if a user needs a document on how to insert a table in word. What would s/he expect from the document? A step by step description of the procedure of inserting a table in a word document.
Don’t take the user for granted. Gauge the knowledge level of the user first. This is what we call User Analysis. If s/he is a non-technical person, start with the most primary information required. Open a word document. Click Table >> Insert >> Table. Select the number of columns and rows required….and so on. Write a document the way you would wish it to be created for you.
Technical Communication calls for writing precise, easily understandable and crisp sentences.
- Write short and crisp sentences as far as possible.
Avoid: Enter the user Id, password and the 4-digit security code generated using the handheld security device and click Submit to gain access to the application that has 3-level security system.
Use: The application has 3-level security system. Enter user ID and password. Generate the 4-digit security code using the handheld security device and enter it. Click Submit to gain access to the application.
- Write grammatically correct sentences.
Avoid: Do not use tags which aren’t necessary.
Use: Do not use unnecessary tags.
- Use appropriate punctuations wherever required.
Avoid: When both the requirements are satisfied the import of the data into the database is started
Use: When both the requirements are satisfied, the import of the data into the database is started.
- Avoid using unnecessary verbose language.
Avoid: While the data import is being done, every record is checked for the errors and flags.
Use: During data import, every record is checked for errors and flags.
- Use active voice.
Avoid: Password verification is done by the system.
Use: The system verifies the password.
- Use first or second person reference wherever possible.
Avoid: The warning message will appear when s/he clicks the Submit button.
Use: The warning message appears when you click the Submit button.
- Use uppercase and lowercase letters at appropriate places.
- Do a thorough self-review after preparing the document.
- Get the peer review done after self-review.
- Use ‘5-digit number’ instead of ‘5 digits number’.
- Use ‘IDs’ instead of ‘Id’s’ in plural.
- Use ‘Home page’ instead of ‘Homepage'.
- Write ‘Internet’ and ‘Web’ instead of ‘internet’ and ‘web’ respectively.
- Use ‘pop-up’ instead of ‘popup’.
- Do not use a period after items in a bulleted list unless they are complete sentences. But, if the list contains a mixture of clauses and complete sentences, put a period at the end of each list item.
- Do not begin a sentence with the word "This" unless its antecedent is obvious.
- Do not use and/or in your sentences. It delays your readers by forcing them to parse the sentence in order to understand it. Instead, use . . . or . . . or both.
- Begin each item in a bulleted list with a word of the same grammatical type. If the first item in a list begins with a verb, for example, then all the items in the list must begin with a verb.
Avoid: Use this functionality for:
* Searching for information
* Log in to the application
* Submitting records
* View details
Use: Use this functionality to:
* Search for information
* Log in to the application
* Submit records
* View details
- Do not use company-specific jargon/vocabulary in the documents that need to be sent to the clients.
- Always write in the present tense.
- Do a spell-check before you send the document to the client.
- Do not use contractions (won’t, can’t, don’t, didn’t etc) in the document.
- Be gender neutral.
- Avoid unnecessary capitalization.
- Use notational conventions for emphasis.
- Use bulleted/unnumbered lists when sequence is not important.
- Use an introductory phrase for lists.
- Use numerals for numbers 10 or greater.
- Use units of measurement consistently.
Inexperienced writers often describe an application's response to the user's input as though it happens in the future. For example, they might write, "When you press the ENTER key, a warning message will appear on the screen." In technical documentation, nothing happens in the future! The future tense causes the reader to worry. When will the message appear? What if it doesn't appear?
Document Formatting
- A style sheet is a template that enables you to manage different formatting styles and apply them in a consistent way across the document
- By defining styles, you can easily maintain consistency between or within topics, in terms of design and content presentation
- Style Attributes help you create your own style sheet by listing out different formats for a particular style
- You can set style attributes by creating style tags
Microsoft Word
Microsoft Word is the most user-friendly and comprehensive text processing tool available in the array of innumerable documentation tools. Here are few tips to use it effectively to enhance your documentation:
- Always check your documents for spellings. Click Tools >> Spelling and Grammar to run spell-check.
- Click Format >> Borders and Shading to enhance the look and feel.
- Click Insert >> Break to insert page or section breaks.
- Create Table of Contents using Insert >> Reference >> Index and Tables. Define header structure before creating the TOC.
- Select the text that needs to be hyperlinked and click Insert >> Hyperlink.
- Click Insert >> Bookmark to add bookmarks for creating internal links.
- Click Tools >> Track Changes to add changes to the documents after review.
