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

Why User Manuals Are Important For Any Product ?

All the companies require content that professionally communicate the benefits of their products. Here in Black & White Tech Writing Solutions we develop a comprehensive user manual for your products to help better user adoption and trim down dependency on technical support forum. We line up our services with your products in order to assist users to become more productive.

User Manual is a technical document intended to provide information and instruction on using a particular system. These are mainly related to software, computer hardware and electronic goods.This manual contains written guides and its associated images and also includes instructions and explanation on how to use the product effectively and efficiently.

User-Manuals or user guide tells people how to use the product in an efficient way. User guide includes information about product’s feature and highlights the main features that are used frequently. User guides usually contains step-by-step description about how to use a particular system. Good manuals are limited service, expensive to produce, the territory of experts, and difficult to maintain. The guide comes with template with perfect word–to–word link, which allows writer to produce professional looking manuals.

User-Manuals provide information on how to use a particular product. This should reach end users with intent to provide proper usage advice and reduce the risk of bringing the product inoperable condition. Sometimes improper usage of product such as heat and fire generating devices; lasers and high voltage devices can cause serious injuries or death. Placing appropriate labels within the manual warns end-users and protects the manufacturer from serious lawful consequences.

Usually manuals are used by engineers or sales persons for explaining the customer on how to use a particular feature on the device. A good comprehensive manual consumes less time in explaining about the feature. This of course requires good technical knowledge about the product and the skills of a technical writer.

User-Manual serves as a sales literature for your product. None of your product brochures or case study will provide enough information for a sales person or an engineer, who is looking for a particular feature. Only user-manual/guide will provide everything in one place that is requested by a client before raising quotation.

Any technical document including user-manual represents how you treat your customers. You really don’t want your customer to be angry or confused and think that your product is useless and wasting his time. So, we recommend each and every product should have a user-manual or operational guide.

Black and White tech writing solutions is an end-to-end documentation company. We believe that a writer is a voice that promotes the company’s products, success, commitment, and achievements. Black and white tech writing solution is based in Bangalore, India. We possess a well versed team of creative writers and technical writers. We provide end to end documentation service, which include marketing collaterals, user manuals, White papers, installation guides, and spec sheets. Black and White offers technical writing training for aspiring writers.

For more information on technical documentation visit www.bwtechwriting.com

If you have any queries on technical documentation, drop an e-mail to info@bwtechwriting.com or Contact us on +91 9845236875.

 

Causes of Inefficient Writing

Causes of Inefficient Writing

Sometimes even when the content of the technical documentation is correct (from the technical side) and the grammar is excellent, the writing can be still inefficient. This happens because the writer doesn’t follow some common rules. Here we are going to discuss several factors that usually cause inappropriate technical writing.

Uninviting Look

The idea is that the look of the document is no less important than the information it contains.

To make this factor clear let’s take an example of visiting a restaurant. You’ll hardly go to the restaurant where the food is great, but the dishes and table-cloth are dirty and the waiter talks to you as if he’s hated you all his life, for the second time. The same will happen if the situation is opposite: everything beams with cleanness, but the food is awful. And only if the restaurant has both perfect look and content you have a wish to visit it again and again.

The same with writing. So when a technical writer creates some document he needs to think not only about what he writes, but as well about how to make it look nice to attract the reader. Many specialists don’t use tools for technical writing which can help them.

 Too Much/Little Information

This is perhaps the main reason of inefficient writing. The problem is that too much information makes the document rather complicated for understanding as well as the absence of enough information. And it’s not the writers fault only.

Engineers and other SMEs add lots of information in the documents. On the contrary, people from higher management provide the writer with little information. Thus the writer fails the purpose of writing an efficient document in both cases.

Confusing Structure

Creating a document with the help of some confusing structures is another reason of inefficient help authoring. The readers in the end don’t get informed, but get confused.

Unnecessary Information

Wishing to provide the reader with more information, writers often add irrelevant information to their writing and don’t think of its necessity to their readers. The use of the jargon in technical documentation can confuse the readers even more, because they can simply fail to understand its meaning or understand it differently.

Absence of Visual Aids

There is a good saying “A picture is worth 1000 words”, but writers mostly forget about it. Perhaps they don’t understand that a long paragraph full of numerical data is much more difficult to understand than a pie chart with the same information.

Of course it’s not so easy for writers to control these factors, but following the rules makes the documentation clear and acceptable for the audience indeed.

 

Online Help

Being Windows XP users we from time to time use its Help and Support feature that use both local resources in the form of unequaled set of HTML files on computer and internet resources. Such type of help is called web help.  Among the whole range of tools which are usually used to create web help DocBook XSL, HelpSmith, MadCap Software, RoboHelp, Macrobject Word-2-Web, XDocs Knowledgebase, Help & Manual, chm2web, FAR HTML, HelpMapper, AuthorIt, and Help Explorer Server should be mentioned.

From one hand the web help can exist as a set of web pages and have quite simple structure. On the other hand more complicated structure of web help has a frameset sidebar that has a table of content and gives a possibility to use search and HTML Help.

Web help solutions have both pluses and minuses. First of all they give the potential buyer understandable product preview. They are always updated and can be see using a regular browser. So it doesn’t require any specific technical authoring software. Also usage of a DocBook XSL system gives a possibility to produce any kind of technical documentation in PDF format ready for printing, as HTML ready for publishing on-line or as WebHelp on CD/DVD-roms.

Unfortunately, web help strongly depends on user’s internet connection. Despite the fact that the majority of modern tools can provide context-sensitive web help, in some cases it can be still a problem.

Another way of getting some assistance is to use online help. Online help is any kind of information usually devoted to a specific topic and is provided to the user by means of computer software. Online help introduces the information on the variety of subjects, but more often it is used for giving the user assistance answering the questions on how to use a software application or operating system. If online help is connected to the state of application, that the user is currently operating, with the help of the link, that online help is usually called Context-sensitive help.

Online help can be created with help authoring tools using a wide range of formats: e.g. proprietary (HTML, JavaHelp, Oracle) and open-standard (PDF). To these tools belong DITA and the Open source tool DocBookXSL that is a wonderful resource for generating help files in the following formats: PDF, JavaHelp, WebHelp, eBook, etc.

There are special platforms for delivering help systems. These systems developed by Microsoft for the Microsoft Windows operating system are:

Not open to public:

  • Microsoft QuickHelp (written for MS-DOS and OS/2 called QuickHelp)
  • Help command (MS-DOS, OS/2 and Windows)
  • Help and Support Center (windows Me and Windows XP)
  • Microsoft Help 2(.hxs) (the Microsoft name for HTML Help 2.0 used as a format for Visual Studio .NET, MSDN Library and TechNet products, Office 2007)
  • AP Help 1.0 (.hls) ( based on Microsoft Assistance Markup Language and developed especially for Windows Vista and will be probably used by Microsoft, OEMs, and certain corporate users. The Assistance Platform Help 2.0 engine is currently on hold.
  • Microsoft Help Viewer 1.0 (.mshc) ( developed for VisoualStudio 2010)

Open to public:

  • Microsoft WinHelp (.hlp) (Based on the Rich Text Format, and was included with all Windows  operating systems apart from Windows Vista, where it is available for downloading)
  • HTML Help (Another name is Microsoft Compiled HTML Help and uses HTML, images and JavaScript and other data as a base.)

Other platforms:

  • AmigaGuide (.guide) (the official hypertext document file format made for the Amiga.)
  • Apple Help (.HELP) (Apple Computer’s proprietary platform for the Mac OS 8.5+ operating system.)
  • Flare (MadCap Software’s cross-platform, WebHelp based on browsers)
  • Sun JavaHelp (.js) (made by Sun Microsystems is platform-independent. It is platform-independent (so it runs on any platform that supports the Java Runtime Environment (JRE)), was written in Java programming language )
  • Oracle Help (developed for Java (OHJ) and for Web (OHW))
  • Help library (.HLB) (the official file format designed for VMS.)
  • DotNetHelp (A new Windows format which supports .NET applications.)
  • Texinfo (or “info” is the official documentation system for the GNU project.)
  • Unix man pages (the standard method used to document Unix commands.)
  • Information Presentation Facility (IPF) (used by IBM’s OS/2 system.)

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

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.