Archive for the ‘ Black & White Tech Writing Solutions ’ Category

Tips on Writing User Manual

Writing user manuals is one of the toughest tasks in the field of technical communication. We all know technical writing is writing about complex technical information in a simple, clear and concise manner, which the targeted audiences can understand. Writing a good user manual requires a good knowledge in the field of technical communication. Following are some of the key points that a technical writer should follow before writing any user manual.

UserGuide1

Understand your Audience

One of the most important phases in documenting user manual is to understand the knowledge level of audiences. Depending on audiences knowledge levels, level of information put in the manual varies. If your audience is a computer technician, then it will be appropriate to add some technical words such as database, Control system, circuit, digital systems, and so on. If your audience is a layman who has less or no knowledge of technology, they might not be interested in how software of service works. They just want to know how to fix the things. In most of the cases, you want to know your audiences for a simple reason of giving the appropriate information.

Know Objective of the Manual

Once you are familiar with your audiences, you must ensure that you are adding appropriate information in the manual. Before jumping into documenting manual, make an outline so that you have a fair amount of idea when and where to place the information. Make sure you do not overload the reader with too many details.

Be Clear and Concise

User manuals should contain brief information about each and every topic. Manuals should not be cluttered with words that confuse the readers. Every user manual should convey information in a crisp, clear and concise manner.

Be Conversational

Try to avoid technical words, unless it is required. Readers often gets confused and overloaded with words that they are unfamiliar. User manual must be written in such a way, the reader should be able to get the required information easily. One of the best methods of being conversational is by including FAQ section. This section helps users to get answers to the most common questions that come in their minds.

Include Table of Contents and Glossary

Section TOC (Table of Content) is one of the key elements in user manual. Most of the user manuals are included with TOC to show the organization of the manuals. Inclusion of glossary section will improve the overall accessibility of the manual.

Add Illustrations and Examples

Include images and screenshots wherever necessary. We all know that a single image can speak 1000 words. Using examples while explaining technical information makes explaining easier and reduces inclusion of redundant contents.

Advertisements

How Certification boost your career as Technical Writer

Perhaps you’re feeling stuck in your job! Are you feeling as though you need a boost! Something that could help you to advance, become more professional and more marketable or may be something that would powerfully propel ahead in your career. The answer just might be earning a certification in the field of technical writing.

Technical writing Certification programs have proliferated extremely in the past several years. No matter what field you are in, there’s always a chance to gain certification for it. The main question is can technical certification really help boost your career, or they just a way of the issuing intuitions to stuff their coffers with the cash. Most organizations fail to provide certification which were more likely to boost their career or gain employment, or earn higher salaries that those who are not certified.

Certainly some certifications are more valuable and career boosting than other programs. If you consider pursing a certification in the field of technical writing, it would be wise to pose some tough questions to the institute. Following are some of the questions:

  • What is the reputation of the issuing organization?
  • Do the certification benefits me? Justify the cost?
  • Ask students who have already received certification from the institution.

Black & White Tech Writing Solution P. Ltd is one of the best and most reputed institutes which offer best technical writing training. Those who take up training course from Black & White will learn from veteran trainers who are backed with vast technical writing experiences.

On top of all the fundamental knowledge necessary for all type of technical writing, this course included with many soft skills training which is guaranteed to boost your career.

The Process of Writing a Technical Manual

A technical manual provides most valuable information on a product, service or company’s operating procedure including instruction on how to use, handle, and repair a system. The process of producing a technical manual is a team effort. In most of the cases, a technical writer is given only 10% priority of the whole project. Other priority includes designers, developers, testers, and editors. The whole project picture is usually seen by the project managers. Whether a technical communicator is assigned to do a user manual or technical manual or maintenance manual or any other technical document, he or she should know the process involved.

One of the first steps to document a technical document is to meet with company employee who is capable of providing relevant information on the product or service.  These individuals can provide information that can be included in the technical document, which vary from one organization to another. Varying information includes organizational flow charts, history, equipment, process steps, terminology, additional resources and abbreviations. Illustrations such as charts, graphs, screen shots plays a very important role in comprehending a process and will likely enhances the popularity of the manual.

Before starting-up with any documentation, it is essential to determine the table of contents. Dividing the manual into subject or topics can help the end users; this enhances the readability of the document.

Once the basic flow of the manual is determined, break each category into sub-categories. For example, operation manual should include section on basic operations and also advanced operation procedures. Writers must compile the manual in such a way that the section flows in a natural order.

 

Skills Required To Be a Technical Communicator

Like other profession, technical writing requires knowledge of certain skills. Skill sets primarily involves writing and illustrations. The world of technology and technical communication has evolved dramatically. Following are some of the basic skill sets that a technical communicator should encompass.

Writing Skills

For a technical communicator, writing skills can never be overlooked. A technical communicator should write in a simple, clear and concise language. Write up should convey information for a variety of audiences.

Technical Skills

Technical skills of technical communicators depend on the subject matter. Hardware and software documentation requires different skill sets that a technical communicator needs to bring on to his desk. Usually technical communicators have a technical background. A technical communicator asked to document developer’s guide may need to have a fair bit of knowledge on the platform. When a writer is tasked with advanced weapon system, they might need an advanced degree of engineering as well as solid knowledge of government documentation standards. A technical communicator should possess basic technical knowledge used in a technical process, product or a service which needs to be documented.

Tool Skills

A technical communicator must know various software tools used in technical writing. Since they have to develop document in various forms such as Word, PDF, CHM, and HTML. Writers must know specific tools, like Adobe FrameMaker, RoboHelp, Snag-It, MS word, Adobe Acrobat X pro, Author-It. Depending on the product and client requirements, technical communicators must be able to deliver various forms of documents.

Design Skills

Technical communicators should never underestimate the usage of graphics. Writers should be able to convey their ideas in a document with the help of some basic graphics. Being a communicator we should know that 90% of our brain captures information which is graphically depicted.

Testing Skills

A technical communicator should actively participate in testing the product, service or process. It’s a sole duty of writers to correct the spelling mistakes in the product.

The above mentioned skills are the basic skills that a technical communicator should posses. Skills may vary depending on the educational background of the writer and his field of experience.

Why do we need technical writers to write technical documentation?

Technical writing is currently a booming industry in India. A professional technical writer is the one who handles technical writing in an organization. Knowledge on industry writing standards and also about the tools that are used to create a more appealing document is necessary for a technical writer. Here in Black & White Tech Writing Solutions we have a team of talented technical writers who possess the knowledge and talent in creating technical document of international standards. We help organizations to provide better user adoption and cut down cost on maintaining a technical support forum.

Technical writing is a process of creating documents on complex technical concepts and instructions in simple steps, so that users can perform intended tasks in a specific way with ease. The process of writing a technical document involves translating technical information into documents that are both precise and concise. There are different types of technical documentations that include release notes, product installation guides, walk through demos; whitepapers and case studies.

The most commonly known technical documents are the user guides and product manuals. Users of any hardware or software products would be aware of these documents.

A technical writer is a professional who possess technical knowledge with good writing abilities. A technical writer should be able to create technical material in a concise and effective way.

For a technical writer to present information in the most appropriate manner, he/she should first be aware of the target audience and the goal of the document. For example, a user manual for java JDK software will require minimum technical information as the audience here would have more technical knowledge when compared to audience for a user manual of a television, which is written for general public.

Documents can be printed or posted online, but before doing that they should follow some similar guidelines, layout and structure in giving information to maintain professionalism in a consistent manner.

A good technical document should follow many formal standards or guidelines. Technical documentation will have various styles and formats to choose from. These are usually chosen depending on the medium it is used and subject area it has to cover.

Generally, technical writers follow formatting conventions described in a standard style guide. The two most used style guides being MSTP (Manual of Style for Technical Publication) and CMS (Chicago Manual of Style). There are also many tools used by technical writers to make a document more appealing and also professional. The tools are necessary to create or customize both text and visual graphics in the document.

Technical writers generally follow five procedures in creation of a technical document. They are:

  1. Analyzing the audience for whom the document is been created.
  2. Collecting all the required information of a product that is been documented.
  3. Coming up with a project plan and a document layout to give a structure for the document.
  4. Proof reading the document created to make sure there are no typographical errors, such as errors in grammar or spelling.
  5. Sending the document for detailed final review from subject matter experts or the technical team.

On acceptance of the document there is a sign-off mail sent by the reviewed team confirming the successful completion of document creation.

Though in some smaller organizations the developers themselves try and create technical documentation, their lack of writing skills are clearly displayed with inconsistent document structure and improper format.

To create a good technical documentation it requires more knowledge about writing format other than just having a good command over language, which a technical writer is trained to possess. Documents that are created with proper documentation knowledge confirm proper use of styles and accuracy in both technicality and writing.

Black & White Tech Writing Solutions Logo

Major Challenges Faced By a Technical Writer

Black and White Tech Writing Solutions

Each job has its own challenges and opportunities. Lets us understand the challenges faced by tech writers in the field of documentation. Here in this blog let’s have a discussion about the challenges faced by tech writers. Following are some of the major challenges faced by tech writers in the field of documentation.

  • Analysing the Audiences

Knowing the knowledge level of the audiences is the major task associated with tech writers. Before getting started, writers should have a thorough knowledge of the end-users. Writers should also have a clear knowledge about purpose of the document, media of publication, and location of the end-users.

  • Gathering Required Information from the SMEs

Most of the times, SMEs might not have time to explain the product or process to the documentation team. It is a sole duty of tech writers to gather clear information from SMEs.

  • Reviewing the Document

Once the document is completed by tech writers, it must be reviewed. Often SMEs (Subject Matter Experts) find it difficult to review the document created by tech writers and give their feedback. This problem is faced by all tech writers. This problem can be solved to a small extent by distributing the work to non-writers and look how far they can understand the product or process using this document.

  • Team Work

Personality conflict occurs when people work in a group. It is applicable to tech writers too. Generally once a document is completed; it will be reviewed and edited by senior writers or by SMEs. This is to ensure that proper information is conveyed in this document. But, this leads to clash between SMEs. Often, writers find it complicated to implement suggestions from various sources.

  • Need for Quality Document

Most of the software developers feel that tech writing is not much important as development. The condition has changed, now everyone is expecting a quality document for their product and services. Now, success of the product lies in the quality of the document.

Following are some of the other challenges faced by tech writers

  • Little or no information about the product or service.
  • Computer and tool problem.
  • Last minute changes.
  • Limited access to product.
  • Poorly defined products.
  • Lack of control over the work environment.
  • Deadline

Black & White Tech Writing Solutions Logo

Help authoring tools

Technical writers in their work use a lot of different software.  These can be a Help Authoring Tools or HAT, content management systems and version control systems. To Hat belong Adobe RoboHelp, Author-it, Doc-To-Help, FAR HTML, HelpIQ, Help & Manual, Help Generator, HelpNDoc, HelpServer, HelpStudio, MadCap Flare, Sandcastle and many other.

It has several basic and auxiliary functions. To the first group belong file input and help output. File input either allows importing a text produced by any kind of program or gives the technical writer an opportunity to create a text using an editor within the tool. Depending on what HAT tool you use the format of the imported file can be different. For example, ASCII, HTML, OpenOffice Writer , Microsoft Word, Microsoft WinHelp, Microsoft Compressed HTML Help etc. HAT also can put the files out as a compiled Help file and non-compiled file formats. The formats that are normally used for outputting are: WinHelp(*.HLP),  Microsoft Compiled HTML Help (*.CHM),  Adobe PDF, XML,HTML, JavaHelp and so on.

As it has been stated HAT tools have also some auxiliary functions for technical authoring. The functions include: automatic or assisted Index generation, automatic table of contents, spelling checker, image editing, image hotspot editing, import and export of text in XML files, for exchange with computer-assisted translation programs.

ImageImageImageImageImageImage