Technical Writing Guide

Instructional Designing: Basics

2011-10-18T23:16:00.000-07:00

Instructional designing is an upcoming field in India. There is a wide gap btween what is taught in classes and what is actually learnt. Instructional designing aims to fill the gap by designing user friendly training programs. Instructional designing designs training from learner’s point of view by effective presentation of content and by fostering interaction.

Instructional designing basically relates with the systematic development of learning objectives using instructional concepts and theories. In simple language, instructional designing is concerned with making learning as interesting as possible.

Instructional designers work with ID Team comprising of graphic designers, programmers, project managers, etc. to provide:
- Self-paced learning
- High level of interactivity
- Vivid simulations and animations
- Effective learning

My next post will talk about the difference between technical writing and instructional designing.

Writing Masterpieces

2010-12-31T01:13:00.000-08:00

As writers, we are expected to be creative and full of "Quick Ideas" and "Document Fix It" Glue. But how much is it possible while following a pressing deadline or meeting other work items scheduled for the day/quarter. As writers we all face the issue of great creative expectations bounded by time crunch factor. What is the output - Document Errors/Missing Creativity/Lack of Motivation.

The real question is how to maintain a balance at workplace and create great masterpieces? Well, there are no defined rules. My post will talk about some fundamentals that can be practiced.

Focus - Focus on each paragraph, sentence, words, spellings, punctuation and style
Letting Go - Letting go your ego. Work with the end target audience and end goal in mind
Realizing your strengths (n weaknesses) - Use your strengths while writing. Create writing strengths by building your knowledge in related fields/models like Bloom's Taxonomy, Instructional Designing strategies, etc.
Bigger picture - Relating your priority with the organization's goal
Giving your best shot - Do your part with honesty and dedication. Whatever be the results, you know that you played your part well.
Worklife balance - Your family, friends’ n work off course :)

It is also very important to do self review and peer review to get rid of errors as much as possible. Above all the end results and customer feedback matters. So make sure if you are writing a sales kit, you have taken interviewed several sales personnel before writing for them, have thorough discussion with SMEs to understand the sales product/service and above all take feedback on v 1.0 from them all (target audience, SME) along with your Seniors (Bosses).

Style Guide in Technical Writing

2009-09-24T04:05:00.000-07:00

As technical writers, you are often asked to create or refer to style guides? Why? Style guides can help in improving document quality and in standardizing document presentation. For example what is correct - 5 or five? Style guides can help you decide this. Let’s understand the basics of style guides.

What?

Style Guide is a set of standards that highlights the preferred writing style, punctuation, spelling, and formatting used for various publications by an organization. You can refer to industry-accepted style guides or create your own in-house guide.

Why?

Consistency – Ensures consistent and uniform look of all publications, thus enabling readers to seek information with better ease and speed. For example, if you are using American English, you will make sure you write “analyze” and not “analyse” throughout your document though both are grammatically correct spellings.

Easy Writing and Editing – It is easy to create or review a document if the writing rules are already clarified. You can refer them any point in time to make sure you are using the correct format.

Effective and Fair Writing – Adherence to style guide helps to create neutral and effective publications regardless of each author’s personal writing style. For example, you will follow the capitalization rules as specified in the style guide instead of your own way.

Examples:

Technical Documents

2009-07-18T00:00:00.000-07:00

Technical Writing involves creating a wide range of documents that varies across organizations. These documents are created using various tools like MS Office, FrameMaker, RoboHelp, Adobe Creative Suite comprising of Photoshop, InDesign, Flash, and so on. Some of these technical documents are:

User’s Guide: Companies that offers products or services need to have user guides to explain how to use the product/service. The Guide contains detailed description of product/service features and instructions to use them.
Online Help: The growth in online media has popularized creation of Online Help by companies. The Help provide assistance on using a particular product/service.
Installation, Reference and Troubleshooting Guide: Companies needs to familiarize the users how to install or repair their product or software. This document provides steps to install and troubleshoot the product or software.
Release Notes: Companies create Release Notes to familiarize the users with new features, enhancements, fixed issues and known issues of the product or software. These are publications distributed along with product in the development or test state. These are also created every time a bug is fixed or an enhancement is made on the product.
Technical Advisory: This document describes an issue, its cause and work around.
Marketing Collaterals: Companies create marketing or sales document to market and promote their product or services. Common examples of marketing collaterals are business proposals, white papers, datasheets, sales brochures, flyers, catalogs, posters, and presentations.
Training Materials: Companies require training their employees or external customers. These are publications created for use in self-paced training or classroom environment. Common examples are tutorials, workbooks and instructor’s guide.
Miscellaneous: Occasionally, companies need other type of writing intended for publication done for them. For example, documents like newsletters, technical reports, resume, press releases, etc. are created by technical writers.

Tools in Technical Writing

2008-07-29T23:47:00.000-07:00

Technical writers create documents in various formats like electronic publishing, print, online help, etc. The various tools used to produce technical documents are described below.

Publishing Tools (Microsoft Word, FrameMaker) - Microsoft Word is actually the most popular tool for publishing in spite of its bugs and limitations. It is easy to use, review, and make changes. But with larger documents (more than 500 pages), Word behaves a bit inconsistently and may get corrupt. Here, FrameMaker creates more stable documents. Styles are very consistent and rigid in FrameMaker and it can handle large amount of text and graphics.

Help Authoring Tools (RoboHelp, Epic Editor, AuthorIt) - With the increased use of the Internet, users have become more accustomed to using online information. Online help is searchable and helps the users to resolve their problem or query easily rather than going through pages and pages of manuals. Help Authoring Tools like RoboHelp, Epic Editor, AuthorIt are used to create online help.

Template Designer (Indesign, PageMaker, QuarkExpress) - Template designing tools are used for creating documents that require a flexible layout or strict typography demands. It is easy to create and design datasheets, whitepapers, brochures, solution sheets and other marketing and technical documents using these template designer tools.

Image Editor (Photoshop, SnagIt, CorelDraw, Illustrator) - Graphics are an important part of any document. As rightly said "a picture is worth more than words to say." Image editors are used for image designing, capturing, cropping, morphing and all sorts of image editing.

Web Design Tools (Dreamweaver, FrontPage) - Web design tools are created to deliver content to end users in the form of web pages. You can create both static and dynamic web pages using web design tools.

Screen Recording Tools (Camtasia, Captivate) - Recording tools like Camtasia and Captivate are used to create product demos, engaging simulations, scenario-based training, and randomized quizzes. In addition, it doesn't require programming knowledge or multimedia skills.

Multimedia Tools (Flash, Max 3D) - Multimedia tools are used to create audio and video content. Multimedia tools like Flash and Max 3D can be used to create interactive animations and demonstrations.

These are some of the basic tools used in technical writing. Other tools like Teamsite, Lectora, Visio, and so on are also used to create content and graphics.

Fields in Writing

2008-01-17T04:03:00.000-08:00

I will share my views on the fundamental terms associated with writing. Writing involves fields like:

Creative writing: It is a broad field that involves writing on any topic - fiction or non-fiction. Generally, creative writing includes writing short stories, poems, novels, etc. The core element of creative writing is to look at the world from a different perspective and express your thoughts and ideas clearly and forcefully.

Content writing: It deals with writing contain on various domains ranging from business to travel, art to science, health to politics. Generally, content writing is linked to writing content for web (portals, wiki, or blogs). The core element of content writing is to understand the target audience (customer or prospects), design and create content that can grab attention and is useful to the audience or reader of the content. It may also refer to writing content on the basis of search engine optimization to achieve high ranking on search engines.

Copy writing: In simple words, copy writing is a writing that sells. Generally, copy writing is linked with advertising and media with the aim to promote a person, a brand, or an idea. The core element of copy writing is write to sell a product, service, or pursuade your target audience to select your business or organization. Copy writing can range from creating body copy, proposals, whitepapers, newsletters, brochures, press release, and other marketing collaterals or promotional materials.

Technical writing: It refers to writing technical concepts in an easy to understand format. Today we cannot imagine a life without cell phones, personal computers, and other hi-tech devices. Thus, knowing about these devices, their installation, and troubleshooting methods have become more important. Technical writing involves writing on these devices and creating online help, user guide, installation guide, datasheet, reports, and other technical materials.

API writing: It relates to writing on application programming interface. API is a source code interface provided to interact with applications. API writing involves writing for programmers/developers who can refer to the API or update or fix them. API writing helps product users to learn about the API functions, their purpose, parameters, return values, etc. that are available to their applications. In simple words, it is writing about what a function is supposed to do.

Editing/Reviewing: It refers to making changes to a document, audio or video to make it adhere to agreed standards. Editing or reviewing involves checking for consistency, grammatical correctness, and adherence to specific style guide or style sheet. This activity ensures that documentation or audio/video material is of good quality.

Instructional designing: Instructional designing basically relates with the systematic development of learning objectives using instructional concepts and theories. In simple language, instructional designing is concerned with making learning as interesting as possible.

Journalism: It refers to writing, reviewing and creating articles and news. Generally, journalism is related to writing for media like print (newspapers and magazines) and electronic (television, radio, and the Internet). Journalists report and write on a variety of topics including politics, economics and business, health and medicine, education, sports, lifestyles, clothing, food, pets, and relationships. The purpose of journalism is to inform, educate, and enlighten the readers.

All these forms of writing supplment and complement each other. The basic requirements for venturing in these fields are flair for writing and a creative bent of mind. Above all, each field in writing requires hard work, focused mind, and a learning temperament.

Document Development Life Cycle

2007-07-06T02:44:00.000-07:00

Document development life cycle (DDLC) includes the various stages involved in structured document creation. It ranges from requirement analysis through maintenance of the completed document. The DDLC comprises of the following stages:

Project Start-up
Requirement Analysis
Designing
Developing
Testing
Publishing
Maintaining

Project Start-up
Project start-up generally involves the creation of project plan. It includes understanding the project objectives and constraints in terms of time, quality, and cost. The scope of the project is clearly defined along with standards to be followed throughout the project. This phase also involves identifying key personnel responsible for providing, reviewing, and approving document content.

Requirement Analysis
Requirement analysis for documentation includes Audience Analysis, Need Analysis and Task Analysis. You try to understand the learning gap and come up with strategies required in achieving the project goal. You also decide the format and the delivery media for the document at this phase.

Designing
Design phase basically deals with collecting and organizing data. Design phase involves planning the instructional and media strategy and creating the course outline. High level design and low level design related to instructional and media strategy are created, verified, and validated.

Developing
Developing the document requires actual writing of the document, and integration of the various components (graphics, glossary, search items) of the document. This phase also involves document reviews and revisions and management of documentation issues. Now, the document is ready for testing.

Testing
Testing involves measuring the quality of the document. This involves review by quality analysts on parameters like correctness, completeness, adherence to standards, and usability.

Publishing
After fixing the all the testing bugs the document is ready for publishing. After all the hard work this phase relates to actual delivery of the document to its target audience.

Maintaining
Maintenance involves maintaining the deliverables. For example, it may involve content reuse analysis and elimination of redundant data from the document sets. It may also include template revision or inclusion of new product features.

Understanding the DDLC helps in efficient and quality document creation. Happy Documenting!!!

Story of a Fresher Technical Writer

2007-05-04T04:49:00.000-07:00

I completed MA in mass communication with a distinction. The first few days were spent enjoying my success. But then with each passing day I had to decide about my future. In the meantime I got a call from XYZ Computer Solutions for the post of technical writer. The company was hiring a fresher with a flair for writing technical and basic computer skills.

I got selected. I was excited about my first job and studied the company’s Website in detail. XYZ Computer Solutions was into Telecom and Enterprise IT solutions. My first day at office was an induction session on the company, its staff, and its core competencies. The company had 50+ employees and I was the only technical writer. I was introduced to my team comprising of six developers and three testers. We were reporting to Project Manager – ABC Department.

The next day I was asked to go through the company’s product lines and document repository. They also asked me about my familiarity with tools like Adobe FrameMaker, Robohelp, MS Word, and Visio. I had worked on MS Word but mainly for writing letters or assignments. Here I was to format content as per standard templates. I was all lost. Everyone appeared so busy that I didn’t know where to start.

One week passed in confusion. Then my project manager guided me by asking me to go through tutorials on authoring tools. He also asked me to prepare a style guide for consistency. Google appeared my savior and protector at the time. I took one month to gain a basic understanding of the profession. Soon I started writing my first online help. It wasn’t that difficult after all.
The few lessons that I learnt as a technical writer are:

Prioritize your work: There is always a lot to cope up, especially if you are the only technical writer. Prepare to do list. Also, do not feel shy of seeking time if you already have some important work to do.

Practice and update your writing and technological skills: Familiarize yourself with various authoring tools and you will always find scope for improvement.

Specialize in a domain of your choice (to improve your market value): Join a weekend class or build your expertise in a subject matter of your choice - ranging from telecom to intellectual property. For example, I enrolled for a Microsoft Certified Systems Engineer (MCSE) after joining XYZ Company as I had to write a lot on networking.

Develop a reading habit: Reading can involve everything from newspaper to ezine on technical communication.

Be confident: Knowledge is power. Initially the subject matter might appear a bit complex. Read and surf the net to find answers to various terminologies. Make notes. You’ll gain expertise in the subject with time.

Skills in Technical Writing

2007-03-14T02:18:00.000-07:00

Technical writing is gaining recognition with time. To become a technical writer you should have strong writing, editing, and instructional designing abilities. You should be able to grasp complex subject matter. You should be able to write clear, concise, and user friendly documents. There are personal and technical attributes required in becoming a good technical writer.

Personal attributes
As a technical writer you should be creative as well as focused. You should have good communication skills. You should be able to write simple and grammatically correct sentences. You should know how to organize your thoughts and write them down convincingly. You should have the ability to interact with management as well as end users.

Technical attributes
In general, people with degrees in journalism, mass communication, English literature, and engineering are favored. However, this varies from company to company. For example, a Telecom company will prefer a person with technical or engineering background whereas a company into legal documentation will prefer a person with a degree in law.

With the increased use of desktop publishing, technical writers increasingly are responsible for the publication process including graphics, layout, and document design. The following are some common tools used by technical writers:

MS Word – Basic and Advanced
Robohelp
Dreamweaver
Photoshop
Acrobat
Pagemaker
Framemaker
Flash
HTML

If you are not familiar with these tools you can learn them with time. There are online tutorials available to learn these tools at your own pace. Above all, your ability to write well will matter. Companies hire inexperienced writers and train them in these tools and other aspects of documentation development life cycle.

Technical writing is territory of specialists who know how to keep the right balance of content, grammar, and style to reach the documentation goal. As technical writers you have to produce quality documents allowing people to adequately and correctly use technology. You might have to write for people with different experience level. Always keep your target audience in mind.

Introduction to Technical Writing

2007-03-08T22:37:00.000-08:00

Technical writing is a growing field. In a recent survey conducted by Money Magazine and Salary.com technical writing was ranked as 13th best job in the US. It is also growing in India with more and more people joining the fraternity.

Technical writing is writing technical concepts in an easy to understand format. Today we cannot imagine a life without cell phones, personal computers, and other hi-tech devices. Thus, knowing about these devices, their installation, and troubleshooting methods have become more important. Growing professionalism, cut-throat competition, and lack of time has made the field of technical communication and documentation more interesting and challenging.

Technical writers are required to handle various aspects of documentation ranging from creating hard copy or online documents to other written instructional information. Does technical writing limit your imagination and creativity? No doubt technical writing is more factual. But there is always a scope for making your writing interesting and user friendly. Technical writing and instructional designing aims at making the write-up creative, navigational, and easy to understand.

Life of a technical writer revolves around grasping technologies and continuous learning. Generally, people with engineering background are preferred as they are quick in understanding technologies. You need not worry if you have graduated in English literature or journalism and still wish to enter this field. If you have an inquisitive mind and the ability to learn you will do well. Technical writing offers a challenging career where sky is the limit.

Technical Writing in India

2007-02-20T20:36:00.000-08:00

I am a technical writer working in an IT firm. I have a diploma in IT and technology really fascinates me. After struggling and opting for various professions (couple of them ranging from teaching to banking) I have entered into a profession of my choice. But technical writing is a growing field in India. There are always queries related to what technical writing exactly is? There are some more questions:

What does a technical writer do?
Is the field related to engineers or writers?
Are content writing and instructional designing related to technical writing?
What is documentation development life cycle? Is it related to SDLC?

My blog makes an attempt to see the world from a technical writer’s perspective. I look forward to hearing thoughts of people in related fields or people interested in the field. I will try and explain various writing guidelines, tips on document design, technical updates, and simple techniques to create professional documents.