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.

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