Posts Tagged ‘ Technical Writing australia ’

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.

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

Technical Writing Deliveribles

Technical writing is a broad field that embraces different types of documents used for specific purpose in various fields such as science, construction, engineering, industries, and business. Technical documents are written keeping focus on the type of end-users being targeted.

Types of Deliverables:

User Manual: User manuals are the explanations or instructions written to help end users of the product. Most important property of user manuals is simple language, since it is mostly targeted for non-technical users. Writer’s job is to cover all the minute details of the product and include troubleshooting tricks and clear explanation of difficult technical terms.

Reports: Reports are prepared at all levels for various purposes. Perfect formatting and layout design are very important in a report. Reports require severe research and data analysis. Some types of report include case study reports, business and sales reports and academic project reports.

deliverables

Spec Sheets:  spec sheet is an information sheet that illustrates manufacturing and construction process. Spec sheets are widely used in instrumentation, production and medical industries. Spec sheets are mainly targeted to the service providers or contractors, who will analyze the information and estimate the scope and technology required for the completion of the project.

Abstracts: Abstracts are brief guides of a report that summarizes the whole project or report. Abstracts summarize the important information in the report, and include topics or chapters that are covered in the reports.

logo_bw

Difference between MS Word & Adobe FrameMaker

Technical writers have to produce documents in different formats such as printed, online help, HTML, Electronic publishing, etc. Writers must often publish the same text in several formats. Is there a one-tool solution? Is it possible for technical writers to write once and publish many times? Which tool is the best  Microsoft Word or FrameMaker?

What is MS Word?

Microsoft Word is a word processing program. We all use it to one extent or another in our daily activities. MS word is simple and plain. Word is arguably the best one available in the market. MS word was intended to allow users to write letters, memos, short technical publications, user manuals, and articles, design documents, faxes, and many other documents.

Word vs FrameMaker

What is Adobe FrameMaker?

FrameMaker is a desktop publishing program. When it comes to producing complex, business critical documents for web applications, print, and CD-ROM. MS word is excellent for everyday business application and for shorter documents. FrameMaker has been designed to offer superior benefits for producing long documents.

logo_bw

FrameMaker vs. MS Word: What is the difference?

Functionality

Microsoft Word

Adobe FrameMaker

Managing Document

Word does not handle large document well and begins to have difficulties when it goes over 100 pages. Ideal for creating large documents or books i.e. 200+ pages.

Creating TOC or Index

Compiling the TOC and indexes for multiple files takes much longer in Word than FrameMaker FrameMaker creates TOC and indexes across the whole book.

Formatting

Formatting diagrams and images is awkward and prone to crash the document. FrameMaker has a powerful features such as formatting multiple paragraphs, formatting tables,

Graphics

Word’s performance degrades when graphics files are imported. FrameMaker is the best for document creation that includes large amount of graphics, and graphics layout.

Templates

Creating templates in word is limited, as it is designed for writing letters. We can design separate templates for table and paragraphs in FrameMaker, ensuring consistent format for each type.

Printing

We have to print every chapter in a manual seperately. In word, you can select a range of pages such as 1, 3, 5-9, 11-14. In FrameMaker, you cannot print a discontinious range of pages other than odd or even.

Editing and Proofreading Techniques

Careful reading of a document, to detect any errors in punctuation, or grammar, or spelling is referred as proofreading. Proofreading also involves checking elements in the document for their placement, correct dimensions, etc. Revising, arranging and preparing a written document for final production other than creation of materials is referred as editing. Editing involves detection and removal of grammatical, factual, elimination of parts not suitable for targeted audiences, and typographical errors.

proofreading

Following are some general tips for proofreading and editing.

  • As a first screening use spell checker and grammar checker, but do not depend on it.
  • Read the entire content slowly.
  • Carefully read type in very tiny font.
  • Closely review header, footer and page numbers for correct order.
  • Review a hard copy.
  • Read your text backwards.
  • Develop the habit of using more than one method for editing or proofreading your work.
  • Do not try to proofread for everything at once. Focus one issue at a time.
  • Do not use fluorescent lighting when proofreading.
  • Make a list of things to do before proofreading or editing.
  • Create your own editing or proofreading checklist.
  • Most importantly find a quiet place to work

One of the best methods to prepare yourself to proofread is by writing at the end of the day and edit first ting in the morning.

logo_bw

Golden Rules for Technical Documentation

3-13-2013 11-06-54 AM

We have been working on some thoughts about what, how and why we are writing a document. We have come up with few golden rules, which help technical writers to deliver an informative and well-scripted document.

Always keep in mind technical writers Write to inform, not to impress!

Following are some of the golden rules, which each tech writer should follow:

Rule 1: Be Clear

Be clear in your content and think about the real objective of your content. Avoid using phrases and clichés that do not mean anything. Avoid proprietary words that may puzzle the audience and the end-users.

Rule 2: Be Brief

Try to avoid the stuffing contents such as welcome message or overly long instructional text for online forms. Cut your text in half and shorten paragraphs.

Rule 3: Be Creative

Try to be innovative, use a diverse way of representing message, other than paragraphs or texts. Instead of boring paragraphs of text and titles, use billboards, charts, and infographics. These might encourage users to stick with your document.

Step 4: Be Compelling

Know your audience, be excited, be confident, and be bold. Use words that resonate with your audience.

Rule 5: Mind Your Grammar and Spellings

Spellings and grammar distracts users from the message in the content. Always try to implement one idea per paragraph.

Rule 6: Use Templates

Usage of templates enables easier content development, easier gathering of content and makes content consistent.

Pay for quality documentation and your users will be happy. Carefully consider the document formatting, spelling and grammar.

logo_bw

Tools used in Tech Writing

logo_bw

Writing, editing, designing, and publishing skills form the foundation of technical writing, but these skills are just get you started. You need to know how to use help authoring tool, graphic package, publishing tools and web designing packages. Recently WritersUA conducted a survey on tools used in technical writing. The survey concluded that some of the most popular tech-writing tools are Adobe Acrobat, Madcap Flare, Adobe Framemaker, Adobe Captivate, Dreamweaver, Snag IT, Microsoft Visio, and Camtasia Studio.

Though tech writers write various kind of documents, design website and deliver various multimedia training tutorials – publishing program are the basic tool of tech writing industry. Some of the most popular publishing tools are Adobe FrameMaker, Microsoft Word, InterLeaf, and Adobe PageMaker.

Tech Writers are not expected to be experts in graphic artists, but they are expected to have basic graphics knowledge. If you plan to do any kind of documentation, you need to know how to capture screen and edit them manually with the help of tools. Some of the best screen capturing and editing tools are Adobe Illustrator, PhotoShop, Microsoft Paint, Snag IT, and Corel Draw.

Tech writers need to learn at least one Help authoring tool. To create one self-contained Help doc, you need to know how to compile complex document into a usable format. Just ensure that document is completely functional within the limited scope of your project. There are many Help packages available, you can download any help authoring tool and get started. Some of the  most used help tools are Adobe RoboHelp, ForeHelp, HelpnDoc, and DocToHelp.

logo_bw