Technical writing is the process of conveying information in a readable/understandable manner to a specific end-user. Technical communicators write, design, and/or edit proposals, manuals, web pages, lab reports, newsletters, and many other kinds of professional documents. While technical writers need to have good computer skills, they need not necessarily have to write about computers all their lives. "Technical" comes from the Greek techne, which simply means "skill". For a large project, a technical writer may work with a graphic designer, an interface designer, several computer programmers, and a staff of freelance writers to design a huge web site. For a small project or company, the tech writer may be expected to do all of the above, all alone. The first rule of technical writing is "KNOW YOUR AUDIENCE." Writers who know their audiences well are in a position to suggest and implement solutions to problems that nobody else identifies. Whenever one group of people has specialized knowledge that another group does not share, the technical writer serves as a go-between. But technical writers are not just translators, accepting wisdom from experts and passing it on unquestioningly; they also are in the business of generating truth, by choosing what gets written, and for whom, with the full knowledge that later readers will depend on the accuracy of what has been written. Good technical writers are also good trainers. They excel at explaining difficult concepts for readers who will have no time to read twice. Technical writers have an excellent eye for detail. They know punctuation, syntax, and style, and they can explain these rules to authors who need to know the changes required in the document. Although they typically work on their own for much of the time, they also know how to coordinate the collaborative work of graphic artists, programmers, marketers, printers, webmasters, and the various "subject matter experts" (SMEs), who know all the answers but have never bothered to write them down anywhere.
DDLC Document development life cycle (DDLC) includes the various stages involved in structured document creation. It ranges from requirement specifications through maintenance of the completed document. DDLC is the step by step process of preparing the document. This provides the instructions to the technical writers about the document presentation The DDLC comprises of the following stages:
• Audience Analysis
• Usability Research
• Content First Draft
• Technical Review
• Editorial Review
• Final Draft Document
The Audience is often referred to as the end-user, and all communications need to be targeted towards the defined audience. The intended audience of a document is often referred to as who, what, where, when, and why. An audience can always be identified by their varying technical and functional knowledge of the product. This helps the writers to be more specific in terms of using technical terms, presenting graphics, etc… while drafting the document.
Usability Research involves developing the document in a systematic way based on application as well as user performance. Such an audit gives experience in understanding the system behavior and figure out those complex procedures which need more simplification for the reader.
Content First Draft
A first draft document is prepared which is known as rough documentation. This document is made to review by the SME of the organization or Project Manager If any issues are raised while reviewing then the document has to be modified
A technical review involves reviewing the document by the technical experts, for example, developers, testers, project managers, etc whether the technical information conveyed in the document is correct or not.
After the preparation of the documentation get it reviewed by another technical writer. It is nothing but exchanging the documents with each other and reviewing. If any issues are raised just rectify or correct the issues.
Final draft document & Publish
A first draft document is prepared which is known as rough documentation and is sent to SME of the organization or Project Manager for review. After fixing the issues raised, a final document is released and published.
An RFP is a solicitation sent to potential suppliers with whom a creative relationship or partnership is being considered. It is an invitation for suppliers, often through a bidding process, to submit a proposal on a specific commodity or service. The Request process brings structure to the procurement decision and allows the risks and benefits to be identified clearly upfront. It is an "official" statement to vendors about the services required by the organization. It is a document that an organization posts to elicit bids from potential vendors for a product or service. A formal, written document, the RFP outlines information about the organization and details the products and services to be sourced from external vendors. It lays out the specific requirements that vendors need to keep in mind when responding to the bid and outlines how the company will review and award the proposals received.
User Documents offer customers the information they need to use the product. They are primarily user manual which includes some technical explanation. They use everyday terms in place of technical jargon, making it easier for the novice or layman to understand the system.
Product documentation offers a comprehensive description and information on the product. The product documentation has a relatively long life compared to the process documentation. The technical writers start preparing the product documentation while the product is being developed. Writing the product documentation and developing the product is a simultaneous process. The product documentation can be categorized into
• User Documentation: The user-documentation is written for the end-users. It contains elaborate information on how to use a particular product.
• System Documentation: It is primarily intended for the system and maintenance engineers
User Documentation: The technical writer structures the documentation so that it caters to different user tasks and meets the requirements of users with varied experience and expertise. The technical writer must be able to differentiate between the users and system administrators. Technical writers prepare documents for different types of users.
Technical writing tools
The primary tools a technical writer needs are
• Interpersonal skills: If you cannot get along with people, you have no chance of succeeding as a technical writer
• Language skills: Your English (or other languages) must be of a very high level. You must be constantly reading, learning, and improving your writing style
• Curiosity: Technical writing is about learning, and then passing on what you have learned
• Writing, editing, and design skills form the foundation of technical writing. But a technical writer needs to know how to use publishing programs, help authoring tools, web design, and graphics packages.
The types of programs that technical writers need to know:
• Publishing Tools
Microsoft Word, Frame Maker
• Graphic Tools
Microsoft Visio, SnagIT
• Help Tools
Microsoft Word is a word processing program that can be used to create various types of documents like User Manual, Technical Manuals, etc. Documents can be created, saved, and edited in a blank document or via one of the many Wizards included with Word. Several formatting features are also used to make working with Microsoft Word user-friendly.
• Easy Formatting
To format text properties such as color, style, size, etc
• Highlighting the text
Applying borders and shading to text and pages
• Formatting the paragraph style
• Auto-generation of Table of Contents
The Table of Contents will be generated automatically.
• Creating styles
Applying styles to the document for easier formatting
• Auto-generation of Index
Generating the index automatically using keywords
• Create Bookmark and Hyperlink
To create Bookmark and Hyperlink for easier navigation
• Create Tables
To predefine the table length by specifying the dimensions
• Borders and Shading of Pages and Text
To define the look of pages or text using different formatting features
• Spell Checking
Checking for the spelling errors that roll down in the document
• Create Auto Shapes
To create various AutoShapes such as Flowcharts, Connectors, Callouts, etc
• Saving as PDF
Once the document is saved as PDF, it is in read-only mode. The document cannot be edited or modifications are not reflected in the PDF converted document. To convert the document to PDF format, PDF converters should be used.
FrameMaker is a desktop publishing and a help authoring application created by Adobe Systems. It is used by technical writers as a publication tool for creating large documents. Adobe FrameMaker is a powerful page-layout tool. The main attraction to FrameMaker is its ability to handle extremely large documents with ease. This includes keeping the utmost consistency between either one or multiple documents.
In terms of data representation, FrameMaker´s model is straightforward and flat. The text in a document consists of paragraphs, and each paragraph consists of characters. This model is simple for writers to understand and hence gives them a lot of freedom to layout chunks of text while freeing writers from mundane matters such as line-wrapping and justification.
FrameMaker provides for users the ability to name sets of paragraph-formatting options, to ensure consistent font, spacing, and other properties. These names are called formats in FrameMaker, or styles by other programs.
Styles are responsible for the illusion of a larger structure in FrameMaker documents. Chapter and part headings, themselves paragraphs, are affected by using a style, as are auto-numbered lists, which introduce the notion that a paragraph may contain text—the numbers—not typed directly by the author. Counters keep track of numbers to ensure continuity between numbered paragraphs.
Tables and images in FrameMaker documents are treated specially because they can float away from the insertion point. In fact, the only way to force a table into the flow of a document is to attach it to the end of the preceding paragraph or embed it in an empty paragraph. It is useful for writing large and complex documents. Creating a PDF is easy and the user can create bookmarks, links, and other PDF
• Easier to change the layout of a document using Master pages
• A master page is created whenever the user creates a new document. It is used to decide the layout of the document
• Text in tables can be rotated.
• A rotated page with normal headers and footers can be printed, which means that the text can be in Landscape mode whereas the headers and footers are in Portrait mode.
To create accessible PDF documents, you can author your content in FrameMaker and then generate a tagged PDF file, which can be displayed on a broad range of accessible viewing devices.
Microsoft Office Visio 2007 helps to create professional-looking architectural diagrams for documenting and analyzing information, data, systems, and processes. A great variety of drawings can be created ranging from network diagrams to calendars and from office layouts to flowcharts.
• Easy to create architectural diagrams
• Simpler template categories
• Create Theme colors and effects
• Predefined shapes
• Defined with various architectural/block shapes
• Integrate data into diagrams
• Visualize complex information by using Pivot Diagrams Output file
• PDF and XPS file formats • If the drawing requires high print quality, click Standard (publishing online and printing).
• If the print quality is less important than file size, click Minimum size (publishing online).
• To print only a selection of pages, or to specify other publishing options, click Options, and select the settings that you need. Click OK.
• Click Publish.
SnagIT is screen capture software that captures images, text, and video from your Windows desktop. SnagIt delivers customized screen captures with the press of a hotkey. You can produce both graphics and video with this complete capture solution. SnagIt’s video capture is appropriate for simple short screen video capture tasks (e.g. recording how an application fails or recording a monitoring screen). When you register SnagIt, you also receive DubIt, an audio editing tool that allows you to add realtime audio to image and movie clips.
• Simple Capturing Program
Using SnagIt, you can select and capture anything on your screen, then easily add text, arrows, or effects, and save the capture to a file or share it immediately by e-mail or IMPDF and XPS file formats.
• Capture Anything
Capture an article, image, or Web page directly from your screen. Or, capture windows, menus, icons, and regions from any application that runs on your PC.
• Edit and Transform
SnagIt Editor makes it easy to add creative and professional touches to your captures. Transform your images with a full-featured paint tools palette, a variety of edge effects, and practical options for color and size adjustment.
• Share Easily
E-mail, copy and paste, print, and IM your captures, or upload them to your Web site. Snagit helps you communicate any way you prefer.
The Captured images can be saved in different file formats like
RoboHelp is the help authoring tool used frequently. RoboHelp 6 is a complete, flexible, and userfriendly system for building, managing and publishing engaging content for help systems and standalone knowledge bases.
• Easy to use Work in your preferred authoring environment
• Easily build professional help systems
• Flexible Use the content you already have (Importing)
• Publish to a range of popular help formats
• Adobe FlashHelp®, Compiled
• HTML Help
Conducting Successful SME Interviews
Interviewing subject matter experts (SMEs) is one of the most common and useful methods for obtaining the information needed to create quality documents. Successful SME interviews require careful research and preparation in advance. During the interview, good listening skills, critical analysis, and the ability to maintain control of the range and depth of the interview with appropriate tact are crucial to successful outcomes. After the interview, give prompt attention to notes and any required follow-through. When working with hostile SMEs or those with poor communication skills emphasize the strengths of the relationship and develop strategies to work around any weaknesses. INTRODUCTION
Perhaps the most universal and basic method for a technical communicator to gather information is a face-to-face interview with a subject matter expert (SME). SMEs may be engineers, developers, programmers, operators, clerks, or customer support personnel. They are the people who have experience with and knowledge of a particular system, application, product, process, or task that you need to learn about. There is a wide variety of factors that can affect SME interviews. In most cases, the SME has a job to do beyond taking time out of his or her busy day to talk with you. It is therefore critical to get the right information and optimize your interview time. (This is particularly crucial if you work on smaller projects or if you are an off-site consultant; in these cases, your contact with your SME may be restricted even further.) This document explains some of the interview techniques used over the years as a technical writer and communicator. It includes steps you can take before, during, and after the interview to maximize its effectiveness, as well as some tips for handling problematic SME interviews and relationships. The majority of these techniques will apply whether you are a freelancer, a consultant, or a captive writer.
BEFORE THE INTERVIEW
Even before the interview begins, there are things that you can do to build a good foundation for a productive interview experience.
• Define your objectives
• Research the subject matter
• Assemble your interview “toolkit”
• Be on time for the interview
DURING THE INTERVIEW
Often, the face-to-face interview affords you the best opportunity to get content information for your documentation project. (In some cases, the interview may be the only opportunity you will have.) It is important to manage the interview flow so that you will have the time to cover the questions you need to get answered.
• Use active listening skills
• Ask open-end questions
• (Politely) control the interview
• Paraphrase information and repeat it back to the SME:
• Use critical thinking skill s to identify gaps in the information:
• Be accurate
• Organize your materials
AFTER THE INTERVIEW
The following techniques mostly deal with follow-through, and it goes without saying that followthrough is critical in technical writing. Review your notes while the interview is fresh. Immediately after the interview, fill in any gaps in your interview notes and decipher any cryptic notations. If you need to organize your materials better, now is the time to match pages of notes with the relevant screen prints or exhibits.
After the Preparation of the document, reviews are done by the SME (Subject Matter Experts); Project Manager, etc. Reviews are done to check whether there are any issues in the document. Types of Reviews Depending on the status of the organization, reviews have been divided into four types:
• Peer-Peer Reviews
• Technical Reviews
• Editorial Reviews
• Management Reviews
Peer- Peer Reviews
A review which involves more than two or three technical writers of an organization is said to be peer-peer reviews. This review aims at rectifying the spelling and grammatical mistakes. This will be followed by technical, editorial and managerial reviews.
The technical review involves reviewing the document by the technical experts, for example, developers, testers, project managers, etc whether the technical information conveyed in the document is correct or not.
Editorial Reviews are done by the Production Managers. This involves reviewing the document for grammatical, sentence formation issues. After the preparation of the document get it reviewed with another technical writer. It is nothing but exchanging the documents with each other and reviewing. If any issues are raised just rectify or correct the issues.
Reviewing can also be viewed as a way organizations manage work. In reviewing documents, the supervisor or the manager works with staff, often helping to reshape materials to fit group objectives. Team managers and research directors often establish report, proposal, or oral presentation schedules as a way of getting closure on projects. Time overruns are costly and potentially damaging.