w
w
training programstechnical papersinteractive cd'sbooksstudent testimonialscontact us
w
  

T h e  C o m p e t e n c i e s  o f  a  T e c h n i c a l   W r i t e r


As Featured On EzineArticles By Narain Balchandani & Radhika Panicker V

Competencies are described as the ability to do a particularactivity to prescribed standard.
The competencies can be classified into three categories 

  1. Behaviour Skill and Personal Qualities

Good Communication Skill
Communication encompasses building rapport, listening, influencingand creating empathy. Communication is the backbone of the skill set requiredby a technical writer. Unless having good communication skill, a technicalwriter cannot interact with the SMEs /project managers and collect the requiredinformation.

Attention to Details
To get a desired, appropriate and expected result all thedetails concerned should be paid proper attention. Any project may face many issues,if proper attention is not paid.

Team Working
A good technical writer should be a good team player. Unless heis a good team player, he can’t work effectively and produce the expectedoutput. One should have a good understanding of the role within a team and whatneeds to be done .Appreciation for other’s work is also very important toensure that the project objectives are achieved..

Relationship Building
One should have the ability to get on well with other people inan organization and build good relationship with others so that other teammembers will also have good relationship with him.

Flexible BehaviourOne should be able to present his point of view without hurtingother’s feelings and should be always positive in presenting his ideas withoutbeing arrogant.

Ability to Assess User Perspective
One should have the ability to think as an end user andunderstand the requirement and produce the output. Without understanding therequirement and how the information will be used, proper documentation cannotbe produced.

Ability to Quickly Grasp Technology
One should be able to learn new tools and technologies quickly.ie: a  technical writer should  always have a willingness  to learn new technologies .

Active Listener
Only a good listener can become a good communicator, withouthaving good listening skills a technical writer will not be able to gatherinformation from SMEs and managers. So to become a good technical, one shouldbe good listener too.

Enjoy Learning
A good technical writer should always have the passion forlearning and should enjoy learning.

  1. Business Knowledge

Software Development Life Cycle
A technical writershould have the knowledge of the various phases involved in Software Development Life Cycle (SDLC).SDLC isthe complete set of process a developer follows while   developing software.

Document Development Life Cycle
Document Development Life Cycle is the complete logical set ofprocess that author follows when writing documentation with reference to acontext. Similar to SDLC, the DDLC usually runs in parallel to SDLC. The DDLChelps a technical writer to follow each documentation stage in a methodicalway.

Interviewing Skills
While documenting a technical writer may come across variouscomplex terms for which he needs clarification from SMEs or project managers. Toget clarification and collect the required information, a technical writershould therefore have good interviewing skills.

Usability and Testing Skills
The document developed should be user friendly .ie: it shouldbe easily understandable and readable.

Assessment Skill
A technical writer should have good assessment skill. Goodassessment skill helps to understand whether the objectives are met or not andwhether the document is user friendly.

Basic Knowledge of UML
At present UML is the industry standard for modeling a system. Atechnical writer must know what is use case, actor ,system boundary andtemplate for software specification which specify glossary of terms ,use casediagrams, complete description of each case, supplementary specification whichcomprises nonfunctional requirement of a system.

Format for Software Requirement Specification
At present UML is the industry standard for modeling a system. Atechnical writer must know  template forsoftware specification which specify glossary of terms ,use case diagrams andcomplete description of each  use case.

Format for InstallationGuide

  • Configure Software: If installing an operatingsystem users may want to configure their desktop pattern or their mouse .

  • Set Preferences: When installing Word for windows, youcan have the option of choosing WordPerfect Help or not.
  • Create Directories: Users may need to create adirectory on their hard disk for the software.
  • Type Registration number, Phone numbers and Portcodes: Users may need to type in their registration number so that, technicalsupport can identify the user’s system.
  • Choose from list of hardware: Printer, CD-ROM etc.
  • Save, Replace, Rename or Overwrite the systemfiles.: AUTOEXE.BAT or CONFIG..SYS file in Windows.
  • Make a backup copy: Many operating systeminstallations require users to make a backup copy while they are installed.
  • Confirm that the operating system is the correctversion : Users may realize that they don’t have the right operating systemwhich supports the software, so they may become unable to install it.

Format for ConfigurationGuide
Configuration Guidelines are prepared fromconfiguration policy of a company which defines how the work products versionsare changed and managed in a defined policy.

Format for User Guide

  • Every manufactured product comes complete witheither a short instruction booklet or with a more detailed user’s manual.
  • A user Guide usually contains three main parts: FrontMatter, Body and Back Matter.
  • Front Matter: This contains the Title Page, Disclaimer,Preface, TOC&TOF.
  • Title: The document should have a title that tellsthe name of the product or the service and the purpose of instruction.
  • Disclaimer:This describes the copy right andownership of the company.
  • Preface:This section gives a  short description of the product and themanual.
  • TOC-Table of Content
  • TOF-Table of Figures.
  • Body
  • Organize the content :Organize the instructioneffectively with an introduction which gives a short description of the productand the manual.Then mention prerequisites ,precautions if any,documentconventions and the body of the document which contains step-by-step instructionsfor using the product.
  • Back Matter:This part containsIndex,Glossary,FAQs,Referencesand Feedback Form.
  • Index:This lists the index terms which are used inthe document.
  • Glossary:This lists the terms with its definition.
  • FAQ:Frequently Asked Questions
  • Feedback Form:

Reference Guide Format
Reference guides are usually organizedalphabetically by menu item or by problem.For citing a reference ,the name ofall the authors, the title of the journal in the abbreviated form ,volumenumber,year and page number should be given.

Release Note Format

  • A release note usually includes the following .
  • Header:This contains Doc.name(releasenotes),product name,release number,release date ,notes version etc.
  • Overview:A brief overview of the product andchanges in the absence of other formal documentation.
  • .Purpose-A brief overview of the purpose of therelease note with a listing of what is new in this release, including bug fixesand new features.
  • .Issue Summary: A short description of the bug orthe enhancement in the release.
  • .Steps to Reproduce: The steps that were followed whenthe bug was encountered.
  • Resolution: A short description of themodification/enhancement that was made to fix the bug.
  • .End- User Impact: What different actions areneeded by the end- user of the application. This should include what otherfunctionality is impacted by these changes.
  • .Support Impacts: Changes required in the dailyprocess of administering the software.
  • .Notes: Notes about software or hardwareinstallation, upgrades and product documentation(including documentationupdates).
  • .Disclaimer: Company standards and product relatedmessages.      Eg:Freeware,antipiracy,duplication etc.
  • .Contact:support contact information.

Maintanance Guide

  • Software maintenance is the modification of asoftware product after delivery to correct faults,to improve performance orother attributes, or to adapt the product to a modified environment. Thisincludes:
  • Transition: A controlled and coordinated sequenceof activities during which a system is transferred progressively from thedeveloper to the maintainer.
  • Service Level Agreements(SLAs) andspecialized(domain -specific) maintanance contracts negotiated by maintainers.
  • Modification Request and Problem Report Help Desk:aproblem handling process used by intainers to prioritize, documents and routethe requests they receive;
  • Modification Request acceptance /rejection: modificationrequest work over a certain size/effort/complexity may be rejected bymaintainers and rerouted to a developer.

API ReferenceDocumentation

  • Template for Javadoc doclet as under (Eclipse)
  • .Document Title:Specify a document title
  • .Use Page:Select this option if we want thedocument to contain a Use page.
  • .Hirerachy Tree:Select this option if we want thedocument to contain a Tree page.
  • .Navigation Bar:Select htis option if we want thedocument to contain navigation bar(header & footer).
  • .Index:Select this option if want the document tocontain an Index page.
  • .Index per letter:Create an index per letter.
  • .@author:Select this option if we want the authortag to be documented.
  • .Deprecated list:Select this option if we want thedocument to contain a deprecated page.

Administration Guide

  • Overview
  • Managing Users
  • Configure and Schedule Backups
  • Server Settings
  • Server Security
  • Manage Repository Folder Hierarchy
  • Repository Templates
  • Importing Existing Repositories
  • Advanced Website Configuration
  • Configuring Sublime with Apache
  • Import Existing Users
  • Frequently Asked Questions
  • Known Issues
  • Upgrading Sublime

White Paper Format

  • A white paper is generally ten pages in lengthincluding the covers.The paper should contain the following information:
  • Page One-Title page that includes in large type thetitle of the paper,in smaller type the name of the author,the name of thecompany, and the date.
  • Page Two-This should contain all the copyrightinformation.
  • Page Three-The introduction to the companyproducing the paper including a very brief description on the servicesoffered.It should also include a description of what is contained in the paper.
  • Page Four to Eight-The body of the paper.Thisshould be written in a format that gives the reader atleast seven major points.
  • Page Nine-The Conclusion
  • Page Ten-The Back Cover-could contain orderinginformation for additional papers,books,seminars or similar items.This shouldbe brief and to the point.

Case Studies

  • This should have the following format
  • Background:Give a background to yourproject.Remember to include any relevant references in this format.
  • Problem Being Addressed:Describe the problem beingaddressed.
  • Approach taken:Describe the approach taken
  • Problems experienced :Summarise any problemsexperienced.
  • References:Give references in the following format.
  • Title,Author.

Thought Papers

  • A.Introductory paragraph

      1.Write a lead sentence that gains the reader’sattention.

      2.Introduce the thesis or primary argument.

      3.introduce sub-arguments or sub-themes that youare going to use to support your thesis.

  • B.Body of the paper

    • 1.Discuss the sub-themes that are identified in theintroductory paragraph,in separate paragraphs.

    2.Write down page numbers of the book(documentreader or textbook)that are going to be used to support these sub-themes.

  • C. Conclusion

    • 1.Restate your thesis and sub-themes.

    2.Write anyclosing comments.

    3.Software Tools

  • Microsoft Word :is a documentation tool developed by Microsoft. This tool helps towrite, edit and save data as files. It is a powerful tool to createprofessional looking documents.
  •   AdobeFrameMaker: is a documentation tool similar to Word and is developed byAdobe. It combines word processing page layout, graphics and work with longdocuments of capabilities in one document. We can create books, letters, reports,memos etc.
  •   PageMaker:was the first desktop publishing program introduced in 1985 by Aldus Corporation,which was later acquired by Adobe systems. The last version is PageMaker 7.0.
  •   QuarkExpress: is a computer application for creating and editing complex pagelayout in a WYSIWYG environment. It was first released by Quark Inc in 1987 andis still owned and published by them. The most recent version is Quark Express8.
  •    Robohelp:is a help authoring tool that helps to create online help files. This tool letsyou to reduce development time, costs, increase end user’s productivity andsatisfaction and provide a progressive path as your help development needs change.
  •   PowerPoint: is a presentation tool developed by Microsoft .It is a part ofMicrosoft Office Suite and runs on Microsoft Windows.
  •   DreamWeaver: is a web development application originally created by Macromediaand is now developed by Adobe Systems who acquired Macromedia in 2005.
  •   PhotoShop: is a graphics editing program developed and published by Adobe systemsIt is the current and primary market leader for commercial bitmap and image manipulationand is the flagship product of Adobe systems.
  • SnagIT: is a capturing tool that helps tocapture graphics. It is most popular tool used by technical writers developedby TechSmith Corp.

w