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

Skills Required to be a successful Technical Writer

 

logo_bw

Technical writers are the channel between the people who crafts the technology and the users of the technology. Technical writers work in various fields, such as product documentation, software development, information management, usability, Web design, and health information. Although the array of positions in the field, technical writers must possess few specific skill sets to be successful.

Following are some of the basic skill set that a technical writer should possess:

Writing skills – For a technical writer, writing abilities can never be disregarded. Technical writers should write in a clear and crisp way and to be able to convey messages applicably for a variety of end-users.

Tools skills – A technical writer needs to know way around computers, since they are used to create documentation in a variety of file formats. Specific tool knowledge, such as MS Word, Adobe FrameMaker, RoboHelp, MadCap Flare, and even Adobe PageMaker is a must for all technical writers to produce technical documents.

Design skills – Gratitude for the visual is one of the important part of the skill set of a technical writer. Even the most primitive technical documents didn’t comprise of just the written word. With a growing scope the technical writer needs gratefulness for visuals and formatting as well as graphic skills. Depending on the needs, these skills may only need to be elementary or they may need to be very radical.

Ability to write in brief and awareness of tools are necessary skills for becoming a successful technical writer.

Technical Communication

Technical communication is an extensive field that comprises many form of communications that reveals one or more of the following characteristics:

  • Communicating about technical specifications or any related specialized topics, such as software applications, products, medical events, environmental policy and many more.
  • Interacting by using technology, such as help files, web pages, or any social media sites.
  • Providing tips about how to perform something efficiently, regardless of how technical the task is.
  • User manuals help users be more accurate on their own, improving how easily those products gain recognition into the marketplace and minimizing costs to maintain them.
  • Instructional specifications help one group of experts to communicate efficiently with other technical experts. This result in speeding up development cycles, reducing risks and minimizes rework caused by miscommunications.
  • Training programs present people with new and improved skills, which make them more employable and their organizations and products more capable and safe.

Technical communicators or writers have in common is a user or audience centered approach to provide the particular information, in the correct way, at the specific time to make the end-user’s life easier and more dynamic.

bw

 

Document Development Life Cycle (DDLC)

bw

DDLC is a complete cycle of documentation. It is a structured set of various steps involved in creating any kind of document. To achieve success in the field of documentation, a technical writer should at-least have a conceptual knowledge of DDLC.

Following are the various phases of DDLC:

Requirement Analysis:

Requirement analysis is the first and one of the most important phases of DDLC. In this phase, technical writers analyze the project requirement, tools that will be used in this project, and audience knowledge level. Analysis of project enables technical writers to know about the type and need of the technical document.

Project Designing:

This phase includes the content representation and content collection i.e. how the content should be presented, in which format the document should be presented, how much page should be covered to script the requirements, and so on. Technical writers should make an effort to gain as much as knowledge about the technology and audiences from SMEs (Subject Matter Experts) and Internet. A good bunch of information helps a technical writer to prepare an information rich document.

Developing the content:

In this DDLC phase, the actual content is scripted on the basis of project designing and planning. Graphics and illustration are prepared in this phase.

Editing or Proof Reading:

In this phase, the document is thoroughly checked for consistency and errors such as spelling and grammatical errors.

Publishing:

Parent authority publishes documents created by tech writers. Generally, tech documents are published either in hard copies or in digital formats. Several publications options can be used based on the client’s requirement.

Maintenance:

In this phase, a backup of the document is taken for the future use. It also includes collection of further updates and modification of the document.

bw