Want to develop Online Help based on Adobe AIR. Here are some resources to help you learn more:

• A Tour around the new TCS2 Web 2.0 inspired User Assistance
• Try these AIR applications from the cloud HERE. Once you are in, launch any of these apps and press F1.
• Download a sample AIR app created by Adobe RoboHelp 8
• Seminar Recording: Web 2.0 Documentation using Adobe AIR and RoboHelp 8
• Check out “Community Help” on Adobe Labs, which is based on Adobe AIR

Have you used AIR to create any online help systems?

My latest project involves using FrameMaker 9 on Windows Vista. This is my first time using Vista and, let’s say, I’m finding my feet. I’ve had some performance issues with FrameMaker 9 using Vista — and for the first time — FrameMaker crashed on me!

With that said I found this tutorial (http://kb2.adobe.com/cps/406/kb406897.html) on the Adobe site that gives some tips on how to optimize the performance of FrameMaker 9 on Windows Vista.

The performance of Adobe FrameMaker depends on several factors, including the options you select, your workflow, and the operating system and hardware configuration. The performance improvements listed below are most noticeable when you work with larger files. Optimizing the operating system and hardware configuration improves performance in other applications as well.

Before you perform the steps below, make sure to install the latest version of FrameMaker or any FrameMaker updates to the version you are using. FrameMaker updates often include performance-related fixes or enhancements. See http://www.adobe.com/products/framemaker/

Note: The Windows Vista procedures in this document are based on the default interface.

Optimizing Windows

By configuring your system to run efficiently, you increase the amount of memory available to applications and ensure that they run smoothly. Increase the amount of memory available to FrameMaker, quit applications you are not using, or disable nonessential startup applications or fonts to improve the performance of Illustrator.

Virtual memory

Virtual memory allows the system to use hard disk space to store information normally stored in RAM. Because it takes longer to access information on a hard disk than it does to access information in memory, using a portion of the hard disk as virtual memory can decrease performance.

Windows Vista manages virtual memory using a paging file; you define the minimum and maximum size of this file. FrameMaker performs best when the paging file’s maximum size is at least three times the amount of installed RAM.

To create a paging file with a maximum size of three times your amount of installed RAM, see “Create a paging file with a maximum size of three times your amount of installed RAM (Windows Vista)”

TechNote kb404940 at http://kb2.adobe.com/cps/406/kb406897.html

Delete temporary files using the Disk Cleanup utility.

See “Delete temporary files using the Disk Cleanup utility (Windows Vista)”

TechNote kb404917 http://kb2.adobe.com/cps/404/kb404917.html

Display drivers

Some display drivers offer advanced settings for accelerating or modifying graphics display. Sometimes these settings can adversely affect screen redraw performance in FrameMaker.

Try disabling driver-specific features to determine the best settings for use with FrameMaker.

Fonts

If you install only the fonts you need, then you will improve system performance and the performance of applications that access fonts.

Each installed font increases the amount of RAM used by the system, which decreases the amount of RAM available to open applications, and increases the amount of time applications take to display font menus. Use a font management utility to help you manage many fonts.

Startup applications

Applications that start automatically with Windows compete with FrameMaker for available RAM. You can prevent programs from starting automatically with Windows by doing the following:

To disable programs from the StartUp folder in Windows Vista:

1. Quit all applications.

2. Go to Start > All Programs > Windows Defender.

3. In Windows Defender click the tools button, then Software Explorer.

4. In the Category box, select Startup Programs.

5. Select Show For All Users.

6. Select the program that you want to prevent from running and then click Disable.

7. Click Yes to confirm that you want to stop that program from running.

8. Repeat steps 6 and 7 for every program you want to stop from running.

9. Restart Windows:

Note: If the performance of FrameMaker does not improve, then re-enable the icons and shortcuts in Windows Defender.

If the performance of FrameMaker improves, then isolate the performance problem to one or more programs using Windows Defender to re-enable programs.

Repeat this process until the performance of FrameMaker degrades. When you have isolated the icon or shortcut that is causing the performance problem, remove it again and contact the program’s manufacturer to see if an update is available.

To close applications that are specified to start automatically in the registry:

1. Restart Windows.

2. Press Ctrl+Shift+Esc.

3. Click the Applications tab.

4. Select an application name, and then click End Task.

5. Restart FrameMaker.

If performance for FrameMaker improves, then contact the application’s manufacturer for help in permanently disabling it from starting automatically. Repeat steps 2-5 for each remaining startup application.

Optimizing your hardware configuration

The hardware you use affects the performance of FrameMaker: the faster the processor or hard drive, the faster FrameMaker can process information. Other hardware enhancements, such as installing additional RAM, using a multiprocessor system, or optimizing and defragmenting drives, can also improve performance.

Processor speed

The speed of FrameMaker is limited by the speed of your computer’s Central Processing Unit (CPU). Since FrameMaker manipulates large quantities of data and performs many calculations, its speed is greatly dependent on the processor’s speed.

Installed RAM

If FrameMaker has insufficient RAM, it uses hard disk space (that is, virtual memory, scratch disk, or both) to process information.

FrameMaker is fastest when it can process information in memory, without having to use a hard disk.

Hard disks

As you add, delete, and move files on a hard disk, available space is no longer a single, contiguous block. If the system does not have enough contiguous space, it saves fragments of a file to different locations on the hard disk.

An application requires more time to read a fragmented file than one saved to a contiguous location. You can test your hard disk by using “Check your hard disk for errors.” You can defragment files and optimize available hard disk space by using Disk Defragmenter.

As FrameMaker reads and writes information while working on a file, the faster the access speed of the disk containing the file or the FrameMaker scratch disk, the faster FrameMaker can process file information.

To improve the performance of FrameMaker, work on files saved on drives with fast access speeds, such as an internal hard drive, rather than those with slow access speeds, such as a network server (a network drive) or removable media (for example, Zip drive, or floppy disk).

Removable media often have slower access times and are more easily damaged than internal hard drives.

When you want to save a FrameMaker file to a network or removable drive, Adobe recommends you first save the file to an internal hard disk, and then close the file and use Windows Explorer to copy the closed file to the external or network drive, or save the file to the network using Adobe Version Cue.

Printer language

For best results when printing from FrameMaker, use a PostScript printer.

Most non PostScript printers rely on display information, host computer resources, and proprietary printer drivers to relay print information to the printer, so they may take much longer to print than a PostScript printer. See http://go.adobe.com/kb/ts_kb406897_en-us

Looking for more info

Create a paging file with a maximum size of three times your amount of installed RAM (Windows Vista)

http://kb2.adobe.com/cps/404/kb404940.html

Delete temporary files using the Disk Cleanup utility (Windows Vista)

http://kb2.adobe.com/cps/404/kb404917.html

Some of these are plain common sense, however, I wasn’t aware of how Adobe FrameMaker processes information and the tip to avoid saving directly to a network is worth remembering.

Like I said, I’m new to Vista.

What tips can you give me to get the most of it?

Better still, what tips can you give me to get the most of Adobe FrameMaker?

Tags: Acrobat Capture, Acrobat Connect, Acrobat Distiller, Acrobat.com, Adobe Audition, After Effects, Adobe AIR, Adobe AIR SDK, Authorware, Bridge, Adobe Captivate, Create PDF Online, Digital Editions, Director, Distiller Server, Document Center, Document Server, Flex, Flex Builder, Font Folio, FrameMaker, FrameMaker Server, Adobe InContext Editing, InCopy, InDesign, PageMaker, PostScript, Adobe Premiere, RoboDemo, RoboHelp, RoboHelp for FrameMaker, RoboHelp Server, Technical Communication Suite

I have a love/hate relationship with Adobe FrameMaker. Finding a sensible way to move content between Adobe FrameMaker and Robohelp is something I’ve explored for clients. So, this post from the Adobe Tech Comms team was a nice intro to some points I had overlooked.

• Air Help
• Web Help
• HTML Help
• Flash Help
• PDF, DOC

He adds that you can author the help content in FrameMaker or can start with legacy FrameMaker content and once the FrameMaker content is finalized, link it into RoboHelp for further refinement and publishing into various formats.

To bring FrameMaker content into RoboHelp, start a new RoboHelp project and start linking the FrameMaker file (ie book/document) to the RoboHelp project from File menu.

There are screenshots and more details over here: Getting started: Exploring Technical Communication Suite 2

Do you use this combination of tools to refine your online help docs?

I find this a bit cumbersome.

What do you suggest?

Cherryleaf has released details of new courses for FrameMaker users and technical writers who want to fully understand the features of this powerful tech writing application.

UK FrameMaker Training Courses:

• FrameMaker Basic/Intermediate – create and modify FrameMaker documents.
• FrameMaker Advanced -  create template documents and build and maintain multi-chapter books together with Tables of Contents and Indexes.
• Structured FrameMaker – create and edit documents using structured FrameMaker templates, and feel confident with the authoring environment and the steps required to produce a valid document instance prior to export to SGML or XML.
• Creating EDDs – build an Element Definition Document and link elements using formatting rules to a FrameMaker template.
• Importing and Exporting SGML/XML – edit the FrameMaker Application file and create their own applications, and create and update an EDD from a DTD and vice versa. It covers importing SGML/XML documents into FrameMaker and exporting structured FrameMaker documents to SGML/XML.

See Cherryleaf: http://www.cherryleaf.com/fm.htm

You can now download the FrameMaker 9.0.3 patch.

Mahesh (http://blogs.adobe.com/techcomm over on Adobe does a great job of keeping us up to date with all things FrameMaker. This is available through Adobe Update Manager (AUM). This patch (9.0p250) must be applied on top of 9.0.2 (9.0p237) only. You can check for updates through Help->Updates Menu in FrameMaker.

Manish writes that the following workflows are now enabled and/or supported with this patch:

• API Command — The “New document command” in the quick access bar doesn’t get disconnected from the API command “F_ApiDefineCommand”.
• DITA — On converting DITA map, which contains nested topicrefs, to a book the content of the topic files was hidden in folder templates. In 9.0.3, the folder containing template will be labeled as: []
• DocBook — The starter kit unifies the XML and SGML applications and fixes various formatting inconsistencies in the XML application.
• Fonts — Opening/importing files created in FrameMaker 7.2 with virtual fonts applied to the text now correctly shows the text in FrameMaker 9.
• Markers — The correct Index of Marker(IOM) is generated for a file containing Markers that use structured building blocks.
• Memory — Memory leak shouldn’t happen while creating a book with FrameMaker components from DITA map.
• Message Box — FrameMaker doesn’t crash while displaying a message box during FA_Note_PreQuitBook notification, on the second call of F_ApiUpdateTextInset() and when F_ApiAlert() is called from within a FA_Note_PostQuitDoc notification.
• PreserveEntity FDK client — This can be combined with XSLT in XML applications to preserve variables and special character handling when documents are round-tripped between FrameMaker and XML.
• Spelling Checker — This allows words with special characters to be added to dictionary. It also shows the words with suffix “(s)” as correctly spelled now.
• Table Designer — FrameMaker doesn’t crash on switching on different tabs of table designer when context is set for book and panels are iconized.
• Tables — Table row element hides while using DITAVAL filter.
• User Variables — Deletion of multiple user-variables from Variable Pod should not crash FrameMaker.

Image courtesy of Adobe.com

Structured Documents

Manish adds that in structured document, now you can hide child elements even when in Show state if the parent element is hidden using conditional text. This is an additional option.

How Conditional Text works in FrameMaker 9.0.3

Download PDF on how Conditional Text works in FrameMaker 9.0.3

Get the PDF on Acrobat.com - https://share.acrobat.com

DPI resolution for PNG, JPG and GIF files

Adobe says that the dimensions and default dpi resolution for PNG, JPG and GIF files should not get corrupted when imported in FrameMaker.

FrameMaker 9.0.3 Release Notes

Technical information is at: http://blogs.adobe.com/techcomm/2009/10/framemaker_903_available_now.html

Wording of this technical document

Some of the wording is a bit odd. It refers several times to features that ‘may’ work.

What do they mean it may work? When will it not work? And why not?

Maybe I’m just being picky but these vague statements don’t encourage me to believe that it actually works. It’s more like Adobe is saying “well, whatever, it might work…”

I find this a bit odd. Does it work or not?

C’mon guys!

MadCap Mimic 4.0 is a native XML application designed for creating software simulations and tutorials. The newest version lets you import PowerPoint files, has a new Flash engine, print and output options that support conditionalized publishing. While it will take time to dislodge Adobe FrameMaker, especially legacy users, publishing managers and those responsible for running Technical Writing depts should download a trial copy of this.

PowerPoint Import Simplifies Reuse of E-learning Content

You can now directly import files from Microsoft PowerPoint.

• Technical authors and trainers can create a new movie from existing PowerPoint files or insert slides into an existing movie.
• Mimic 4.0 lets you do this by converting master PowerPoint layout slides into master frames.
• Mimic 4.0 supports “.ppt” and “.pptx” formats, as well as PowerPoint images, background images, shape groups, text boxes, and more.

Enhanced Flash

Mimic 4.0 includes a completely rewritten Flash Compiler that improves the image quality of Flash movie output.

Madcap claims that it reduces the file size by three times smaller than with previous versions.

XPS and PDF First-Class Output Types

It also enhances the print output experience.

The Adobe Portable Document (PDF) and Microsoft XML Paper Specification (XPS) print formats are now available as output types, rather than simple exports.

This will help technical writers and others involved in content creation as features associated with first-class output types—such as condition tags—can now be used with PDF and XPS formats.

Additionally, technical authors can use “Page Setup” options for PDF and XPS formats to specify information such as paper size and orientation.

Usability and Ease-of-Use Enhancements

New usability features include:

• Dynamic Help Window Pane Lock lets the translator keep the current Help topic frozen in place while moving around in the MadCap Mimic interface, making it easier to follow steps or other information placed in the relevant Help topic.
• Minimize to System Tray provides an option to place a shortcut button in the system tray (e.g., notification area) of the task bar when MadCap Mimic is minimized.
• Reorganized Frame Editor facilitates the creation and editing of images.
• Expanded Object Support includes the ability to rotate shapes, as well as add loop and arrow shapes to frames.

Other key features:

Like its other documentation and authoring solutions, Mimic offers:

Unicode support for all left-to-right languages; access to these XML files is useful for translating movies into a range of Western and Asian languages.

Mimic is fully integrated with MadCap Flare for multi-channel single-source publishing and with MadCap Lingo, for translation of multi-media elements.

Pricing

MadCap Mimic 4.0 is $299 per single-user license.

Summary

The more I use MadCap, the more I’m impressed with the quality of their products. While it will take time to dislodge Adobe FrameMaker, especially legacy users, publishing managers and those responsible for running Technical Writing depts should download a trail copy of this.

What I like about their products is how well they are inter-connected.

Price-wise, it’s also great value.

If you want a trial copy or are having difficulty getting from their site, let me know and I’ll arrange it.

Likewise, if you have used it, please drop us a line.

What do you think of MadCap so far?

This article explains how to convert large files between Microsoft Word and Adobe FrameMaker.In this tutorial, the source file is the file being converted (Word) and target file is the file that it will be converted into (in this case, a FrameMaker file).

Our goal during this process is to reduce the Word document into an (almost) plain-text document — but keeping its style names, as these will be used to match styles and tags later in the FrameMaker document.

The overall process involves three stages:

• Preparing the Word file for conversion.
• Refining the FrameMaker file in line with the Style Guide.
• Creating the PDF file.

Note: Before you start, print out the Style Guide and use it as a reference during the overall process. This saves you time moving between files and also helps you become more familiar with the Style Guide’s format and presentation as it sits on your desk and is more accessible.

Preparing the Word file

The first step is to prepare the Word file so that its contents will convert more easily into FrameMaker. This involves deleting all formatting that is unique to Word, such as Text Frames.

For example, FrameMaker has very powerful Table of Contents generation features, so you can rely on this rather than trying to import Word’s or hard-coding it to match the FrameMaker format.

To start the process, delete all the Word constructs that need to be removed before the conversion process can start. This involves the following steps:

• Deleting the Table of Contents (TOC)
• Deleting headers and footers
• Deleting local paragraph overrides
• Deleting local character overrides
• Deleting text frames
• Deleting ALL Word specific features
• Deleting linked graphics

The next section explains what needs to be deleted in Word, and provides some information on why we use this approach.

Table of Contents

As FrameMaker has very advanced Table of Contents (TOC) functions, it is much simpler to delete the TOC in Word and then rebuild it in FrameMaker.

In Word, select the TOC and delete it. Save the file.

Note: If you’ve used bookmarks in Word to generate a TOC, delete them as well. The effort it takes to import them into FrameMaker is not worth the effort. FrameMaker can do it quicker.

Headers and Footers

Both Word and FrameMaker have a different approach to Headers and Footers. In FrameMaker, these are setup in the Master page and controlled from there. Trying to import Word’s header and footers into FrameMaker will only confuse it.

In Word, open the header and footer option. Select each one and press Delete. Save the file.

Local paragraph overrides

This involves deleting any formatting in paragraphs (which should have been formatted with Body styles) which has been done manually — rather than formatted with a Word style.

If you import these local paragraph overrides into FrameMaker, they will confuse the tag settings. It’s much simpler to delete them in Word and then rebuild in FrameMaker.

In Word, select the entire document and press Ctrl+Q. Save the document.

Local character overrides

An example of local overrides is when, for example, in Word a paragraph is entirely Times Roman except for the 3rd word, which is in italic. If the italic was set using a character style, the FrameMaker file may assign that style to the 3rd word AND to the remaining words in the paragraph—not what you want!

My suggestion is to delete all local character overrides in Word.

In Word, select the entire document and press Ctrl+Spacebar. Save the file.

Later, in FrameMaker, you will use the Paragraph Designer to modify the style correctly.

Word specific features

All Word specific features have to be deleted as they cannot be interpreted in FrameMaker. Even worse, if you do not do this, they may corrupt the FrameMaker document.

In Word, delete all borders, WordArt, callout boxes, arrows, text frames, etc. Save the file.

Text Frames — Word uses text frames to create what FrameMaker calls a side-head, i.e. text that appears in the left margin column. To recreate the Word text frame in FrameMaker, create a tag in FrameMaker called ‘TextFrame’ and design this in accordance with the style guide.

Linked graphics

Some Word documents ‘link’ graphics (Insert | Picture | From File) to the document rather than using the traditional cut/paste approach.

For a Word to FrameMaker conversion, this means that when you open the RTF file in FrameMaker the graphic file have to correctly link to the same folders as those in Word. In theory, this should work, but in my experience, this does not always work. Instead, follow these steps:

In Word, select each graphic file, save it with a unique name, e.g. Architecture.gif etc, and store it in the project folder. Once this is done, delete all graphics, and Save the file.

Note: In FrameMaker, you will import all these graphics back into the document.

Once all these steps are completed, you then need to modify different parts of the Word file, depending on how it was created.

Note: This does not involve deleting content as we have done above, but modifying how it is constructed, for example adjusting how the number and bullet lists are formatted in Word so that they can be imported into FrameMaker with less data corruption.

You don’t need to delete these constructs, but you do have to adjust their presentation otherwise they will create confusion in the FrameMaker file, for example you could end up with two bullets for every list entry rather than one.

For the conversion project, this involved managing the following areas:

• Master Pages and sections
• Headings
• Numbering
• Bullets
• Cross-references
• Artwork
• Spanned Columns
• Books and master documents
• Styles and tags

Master Pages and sections

FrameMaker uses Master Pages; Word uses sections.

In Word, sections are often used to insert different headers and footers throughout the document. FrameMaker’s approach is totally different.

Figure 1 – How to access FrameMaker Master Pages (View | Master Pages).

In Word, delete all section breaks. You can search for ^b to find all occurrences. Save the file.

Headings

FrameMaker doesn’t care how headings are named. Because of this, you don’t have to modify the style names in Word before the conversion — unless you want to change the style names to reflect the target template.

However, it’s recommended that you delete all redundant headings, and other redundant styles, as they hold no value.

In Word, delete all redundant headings (Format | Styles and Formatting) and save the file.

Figure 2 – In Word, delete all redundant styles and headings

Numbering

If your Word document uses automatic numbering and styles, you’re in luck! However, if the numbering has been done manually, delete the numbers (but not the styles) in Word.

Then, when you open the file in FrameMaker, you can attach a style with numbering applied. You will probably have to do some resetting to 1 and so on, but this is straightforward process in FrameMaker.

In Word, search for all numbers applied manually. Delete the numbers, but not the styles. Save the file.

Bullets

Like numbering, Bullets were done hopefully with styles and not manual overrides. If styles were used, then keep the style names but delete the bullet from the definition.

In Word, search for all bullets applied manually. Delete the bullet. Save the file.

Figure 3 – In Word, select pre-defined bullets and numbers

Note: If the bullets were done by hand in Word, you may find numbered paragraphs in FrameMaker with two bullets—one defined by the FrameMaker tag, and one kept from Word during the import. The quickest way to fix this is to delete the unnecessary bullet by hand. When you open the file in FrameMaker, the bullets should appear correctly as a result of FrameMaker‘s numbering system.

Cross-references

In Word, you can only cross-reference within the same file; by contrast, FrameMaker can cross-reference among other files within a Book. When FrameMaker reads a Word file with cross-references, it finds obscure marker such as “_Ref565989”. These are of no use to FrameMaker and need to be deleted.

In Word, delete all cross-references and re-create them in FrameMaker by hand. Save the file.

Artwork

Any artwork that was cut and pasted into a Word file can be imported directly into FrameMaker. However, there are two issues to consider:

1. The quality of ‘Cut and Paste’ files that you bring into FrameMaker often degrade, i.e. lose quality. Though it may be time-consuming, it’s recommended that you re-create these in PhotoShop and then import them into FrameMaker.

2. Linked graphics in Word files will not work in FrameMaker as the link settings affect what happens on the FrameMaker side. As discussed earlier, delete these files, save them individually, and then import into FrameMaker (File | Import | File).

Spanned Columns

In Word, delete spanned columns. These could open in FrameMaker as one pica wide and confuse FrameMaker’s setting. Delete the spans and re-build them in FrameMaker.

Books and master documents

Word has a Master Document feature that can be used for managing complex long documents. However, I strongly advice against using this feature; it is very unreliable and prone to corrupting documents. In turn, FrameMaker uses the concept of a Book to assemble project files and is very stable.

Figure 4 – FrameMaker’s Book feature

For the test conversion project, we use three files to create the overall ‘Book’; cover sheet; table of contents; main user guide pages. When working in FM, note that each of these files has a different master page and you need to update each master page where necessary.

Styles and tags

Wherever possible, use similar-named styles in both applications, for example, Copyright style; the only exception is when matching Word’s default Normal style with FrameMaker’s default Body tag.

Note: The fewer styles/ tags in FrameMaker, the easier it is to manage. Delete all redundant styles or tags and merge those that are similar.

Saving the RFT

After completing all these steps, save the Word file in Rich Text Format (RTF).

You can now open it in FrameMaker and refine it in accordance with the style guide.

Figure 5 – In Word, save the file as Rich Text Format

Preparing the FrameMaker file

You now have a modified Word file, saved as RFT, with all Word-specific features removed. The next phase involves:

• Returning the content deleted from the Word file, such as Artwork, headers, footers.
• Updating cross-references, indexes, TOC etc.
• Matching the file with the Style Guide.

To start the process:

In FrameMaker, in order to open the RTF file:

• Select File | Open | File Types | All Files (*.*).

Figure 6 – Select All Files (*.*) to view the RTF file.

• In the Unknown File Type pop-up window, select Microsoft RFT and click Convert.

Figure 7 – Select Microsoft RTF and click Convert

This opens the RTF file, though the format and presentation will be modified slightly from the Word version.

Save the file with a .fm extension. The next stage involves returning all Word content that was deleted (or modified).

Importing Graphics

You have two options when bringing graphics into FrameMaker. You can either:

• Option A – Cut and paste from Word or
• Option B – Cross-reference to a project directory.

Option A usually results in large file sizes as the file has to hold the graphics, whereas in Options B they are cross-referenced from their respective location.

The problem with using Option B is that you have to include the graphics folder when sending the FrameMaker files to other users.

However, the good news is that when you need to update any graphic file in the document (or documents) instead of manually going through each page, you simply update the relevant graphic – and all files are updated automatically!

Figure 8 – Option B – Import files by reference

Unwanted Tags

After you’ve opened the RTF in FrameMaker, you may find that you’ve gained a character tag called Default Paragraph Font.

The only way to delete it is to select the text, choose Default ¶ Font, and re-assign it.

Custom table ruling and shading

To delete custom table settings from the entire FrameMaker document, do the following:

• Select the document.
• Choose Table | Custom Ruling & Shading.
• Select both of the ‘From Table’ settings, and select all check boxes.
• Click Apply.

Updating the Header and Footers

As mentioned earlier, both Word and FrameMaker have a different approach to Headers and Footers. In FrameMaker, these are setup in the Master page.

FrameMaker provides default settings for each document’s headers/footers. Use the Paragraph Designer to modify them and, when finished, select ‘Update All’. You can then return to the Body Pages.

Note: when a Book is comprised of several files, you need to set the page numbers so that there is consistency between each file. To do this, open the FrameMaker file:

• Select Format | Document | Numbering | Page.
• Enter the start page number and Save.

Updating the Table of Contents

This process has 2 options depending on whether you want to integrate your TOC in the main document or you want to create a standalone TOC. For the Klariti project, I used Option B as outlined below.

• Option A – this places the TOC within the main FrameMaker file. This option makes sense when you have a small file that is easy to update.
• Option B – this involves creating a standalone TOC that will form one part of a large FrameMaker book. In this project, we used Option B as the main file was very large and other sections used different master pages, styles etc.

To create the TOC, follow these steps:

• Open the FrameMaker Book.
• Add files where necessary.
• Click Add | Table of Contents.

Figure 9– How to create a Table of Contents

This creates a standalone TOC file. Open this and check that it matches with Style Guide. To update the design/layout, open the Master pages and make the required amendments.

PDF Setup

Before you create the PDF document, you need to define the conversion settings in FrameMaker. To do this, go to:

• Format | Document | PDF Setup.
• In Settings, select Print and for Page Range, select All.
• In Bookmarks, check Generate PDF Bookmarks, and for Include Paragraphs add Chapter Title and Headings 1, 2, and 3.
• In Tags, check Generate Tagged PDF.
• Click Set to finish.

Figure 10 – In PDF Setup Settings tab, select Print from the drop-down menu.

Figure 11 – In the Bookmark tab, add the Chapter Title and Headings

Creating the PDF file

The final step involves converting the FrameMaker files into PDF.

In this test conversion project, we have used 3 FrameMaker files which together form a FrameMaker Book. A book, as the name implies, is a master file that controls the relationship between the files that it contains.

To do this, follow these steps:

• In FrameMaker, open the Cover Sheet FrameMaker file.
• Click the Print Option (File | Print). Select the PDF prnit driver from the Print drop-down menu, for example, Adobe PDF.
• In the options screen, select All and Convert PDF Data.
• Click OK.

Follow the same steps for the other two FrameMaker files. You now have three PDF files based on the FrameMaker files. After all files are converted, close FrameMaker and open Adobe Acrobat.

The next step is to create a master PDF file that will contain the 3 PDF files in the correct sequence. To do this, open the Cover Sheet, and add the other two files as follows:

• Open the Cover Sheet pdf.
• Click Edit | Insert Pages and Add the TOC pdf file.
• Click Edit | Insert Pages and add the Klariti.pdf file.
• Once all files have been added, choose File | Save As and save the file.

You now have the entire FM file in PDF format. The next step is to create hyperlinks for the main headings.

Creating Hyperlinks

In FrameMaker, when you add a table of contents, there is an option to create hyperlinks automatically. However, during this project, this option failed to work. An error message stated that it required additional fonts in order to compile. Therefore, the table of contents file did not create hyperlinks to the chapter titles and headings.

Nonetheless, in Adobe Acrobat, you can manually create these links. To do this, you select the heading and cross-reference it to the relevant page in the file.

Figure 12 – The Link tool in Adobe Acrobat

To do this, follow these steps:

1. In Adobe Acrobat, open the master PDF file, e.g. UserGuide.pdf.

2. Select Window | Bookmarks to display the bookmarks. This option shows the Chapter Title and H1/H2/H3 headings.

3. Navigate to the section of the document where you want to create a link.

4. Select the link tool.

5. Create the link rectangle in one of the following ways:

• Drag the mouse to create a marquee.

• Press Ctrl (Windows) and select the target text with the I-beam. This allows you to fit a link rectangle exactly around the selected text.

6. In the Create Link dialog box, choose a rectangle type.

7. Select a highlight option for when the link is selected.

8. Choose an action type.

9. Choose a magnification option.

10 Click Set Link.

Complete this step for all headings in the TOC.

Figure 13 – The Link Properties option in Adobe Acrobat

This process will create hyperlinks from all headings to their respective sections in the PDF document.

Security Settings

In Adobe Acrobat, there are various security options available. The most relevant for this project is to ensure that unauthorized personnel cannot modify the document.

In particular, you want to disallow unauthorised personnel from copying text from your PDF into their documents, for whatever reason.

Figure 14 – The Document Security option in Adobe Acrobat

To do this, follow these steps:

• In Adobe Acrobat, go to File | Document Security.
• Choose Adobe Standard Security from the drop-down menu.
• Under Permissions, check the four options, e.g. No Printing etc.
• Click OK. Click Close and then File | Close to save the settings.

Figure 15 –Security options in Adobe Acrobat

When you re-open the file, these settings will apply.

Matching the Style Guide

To get the styles to match, review the styles/tags in the FrameMaker file against those in the Style Guide.

For example, if the Style Guide’s Body style is Arial 10 etc, and the FrameMaker file has it set to Times Roman 11, you need to correct this as follows:

• Open FrameMaker and select all content marked as Body.
• Open Paragraph Designer and update the Body fields.
• Select ‘Apply to All’. This updates all occurrences of the Body style in the document.

To stop other technical authors from using the wrong styles, delete ALL redundant styles. For example, the RFT file may have several body styles, e.g. Body, Body + Left, Body + Indent. In FrameMaker, delete all of these otherwise future authors may use these inadvertently.

What do you think?

This approach has worked well for me when converting Microsoft Word documents into FrameMaker. I should add that the latest versions of Adobe FrameMaker offer a more streamlined approach to converting the docs.

With that said, you’re still going to have to clean up the Adobe FrameMaker docs to some extent regardless of how well the converter works.

Over the next few weeks, I’ll look at conversion software and work on the latest version of Adobe FrameMaker, which I’ve now got my hands on.

Let me know if you’ve come across better ways to convert these docs or maybe some of the issues you’ve had in converting these docs.

Thanks.

Master templates let you control the format and positioning of every component in your FrameMaker documents. They are very powerful when they work correctly, but be careful. If you make a mistake, it will take many an hour to clean the documents.
[ad#adc-2]
In plain English this means that if you setup a footer as Arial, size 10, and then apply it to the main document, all footers will appear in this font and this size. Sounds good!

But, what if you wanted to have different footers in the document?

You could hard code every footer.

Hard code means you manually type in the footer. That’s ok for a 5 page document but not if your creating a 250 page user guide.

You need to automate the process, which is where master templates come in.

In FrameMaker, you can create different footers, identify each type, and then apply them where you wish.

You can have different headers and footers for the:

• Cover Page
• Table of Contents
• Index
• Chapters, and
• Copyright pages.

Problems with Master Template

One of the problems I’ve had was that even though I’d created the component, it didn’t appear in the document.

The main reason for this, especially for headers and footers, was that the previous entry was still there.

In other words, you have to remove the previous header and then enter the new one.

When you think about it, it makes sense, but if you don’t know you could get very frustrated.

Tip: Delete the ‘old’ header and insert the new ‘one’ instead.

Workarounds

Numbering chapters, headers, footers, and labels can cause all types of confusion.

One trick I’ve learnt it to cut and paste template settings from a FrameMaker document I know works into the new document.

1. In the first document (i.e. you know works), open the template settings, and select the section you want to copy.

2. In the document you want to update, open the template settings, and paste where appropriate.

3. Click Apply and return to the main document. Your changes should now be reflected in the second document.

I have to admit this does seem like a lot of effort.

If you know a more efficient way to do this, please add it below.

Links

Adobe Framemaker Templates Tutorials – This Adobe Framemaker tutorial discusses the following topics: Exploring FrameMaker Templates, Modifying FrameMaker Templates, Creating Custom Templates, Using Custom Templates, and Importing Formats from a Template

How to Create a Template in Adobe Framemaker – While you can use the templates provided by FrameMaker or other pre-defined templates available to you, you may decide that you want to create your own templates. When you create a template, you can set up various types of formats based on what the template is going to be used for. For example, you may decide to create a special Title paragraph tag or table format for your template.

Introduction to Adobe Framemaker 5.0 – This is a Basic Framemaker tutorial. Look at the ‘create a new document’ to find out how to work with Framemaker templates.

Mimic FrameMaker’s Memo Template – FrameMaker’s Memo template is a great example of a template that can be used as a fill-in form. The layout and fields are pre-defined and you just need to fill in the details for each version of the document. C’mon, let’s create our own template that works in the same, wonderful way!

One File, Multiple Uses in Adobe Framemaker – XML lets you publish the same content across different media with minimal effort. And with the new XML features in Adobe® FrameMaker® 7.0, you don’t have to know XML syntax to create XML-compatible documents. Once a developer has created the structured applications, you create the content in a template using predefined element tags and save the file in XML format. It’s ready to use in an XML-savvy application or to convert into another format, such as WML or VoiceXML.

I’ve made a list of the top 50 technical writers with a web presence. Some of these you might know, such as Darren Barefoot and Tom Johnson. I have also added some other writers from India, Russia and Israel to reach out to a wider audience. I’m sure there are others that I’ve missed. Let me know and I’ll update the list.

This week’s new additions include Alan Houser, Char James-Tanny, Cheryl Locket-Zubak , Colum McAndrew, Joe Welinske, Michael Hughes, and Paul Mueller.

[ad#black]

Update:

Thanks to everyone who sent in other technical writers that I overlooked. I’ve now added:

Geoffrey Sauer, Addison Berry, Jean Hollis Weber, Jim Campbell, Sarah O’Keefe, Shaun McCance, Shira Stepansky, Svi Ben Elya and Scott Able

Back to the list…

Top 50 Technical Writers

In alphabetical order, here is the list.

1.  Aaron Davis and Scott Nesbitt http://www.dmncommunications.com

2.  Amanda Abelove http://www.abelove.com

3.  Amy Gahran http://contentious.com

4.  Andrew Brooke http://techwriters-world.blogspot.com

5.  Andy Schaub www.andyschaub.wordpress.com

6.  Aneesha Myles Shewani www.linkedin.com

7.  Anindita Basu http://writing-technical.blogspot.com

8.  Anne Gentle http://www.justwriteclick.com

9.  Apoorv Durga http://www.apoorv.info

10.Arden Gatlin www.liveperson.com

11.Avi Aharon: GUI Yourself http://gui-yourself.blogspot.com

12.Barbara Stuhlemmer http://techwriterblogs.com/doku.php

13.Berkun blog http://www.scottberkun.com/blog

14.Bill Albing http://www.keycontent.org

15.Bobbie Jo Morrell www.morrellimage.com

16.Bokardo.com http://bokardo.com

17.Chris Borokowski www.user-advocacy.blogspot.com

18.Dan Mabee http://managetechpubs.wordpress.com

19.Darren Barefoot http://www.darrenbarefoot.com

20.David Farbey http://www.farbey.co.uk (updated url)

21.Dawn L. Brown www.dawnsdesktop.com

22.Dr. Macro http://drmacros-xml-rants.blogspot.com

23.Edward W. Dodds http://edodds.blogs.com/conmergence

24.FastForward http://www.fastforwardblog.com

25.Gordon McLean www.onemanwrites.co.uk

26.Heather Leigh :http://blog.CrazyforWords.com

27.Ivan Walsh, Ireland www.ivanwalsh.com

28.Janet Swisher http://www.janetswisher.com

29.KJ Maas www.kjmaas.com

30.Laura Shaffer Mills www.redwriteblue.com

31.Liz Carver http://www.is-people.org

32.Mark Glinsky www.markglinsky.com

33.Mark Watson www.markwatson.com

34.Matt Anderson http://www.montagecomms.com

35.Mike Brannon www.mikeabrannon.com

36.Mike Unwalla http://www.techscribe.co.uk

37.Paul Pehrson http://blog.paulpehrson.com

38.Paul Stamatiou http://paulstamatiou.com

39.Prakash Rangarajan http://www.cloudtrance.com

40.Robert Wisbey http://www.robertwisbey.com/main.html

41.Robert B. Stepno www.stepno.com/bobres.html

42.Sarah Maddox http://ffeathers.wordpress.com

43.Seth Gottlieb http://www.contenthere.blogspot.com

44.Steve Borsch http://borsch.typepad.com

45.Steven Jong http://stevenjong.net/WordPress

46.Suresh Digital Dreams http://www.techpings.com

47.Susanne Dyrhage www.proz.com/profile/72014

48.Tim McGuinness www.timmcguinness.com

49.Tom Coates http://www.plasticbag.org

50.Tom Johnson www.idratherbewriting.com

New Additions

51. Geoffrey Sauer, EServer Technical Communication Library

Geoffrey Sauer, for his EServer Technical Communication Library at http://tc.eserver.org. Tom Johnson reckons that this is the most popular technical communications site in the world (http://www.idratherbewriting.com/2008/12/02/tceserverorg-the-most-popular-technical-communication-website-in-the-world/

Its readership data at http://tc.eserver.org/about/recent.lasso, shows that it serves 167,000 hits to over 22,700 visitors per day.

52. Addison Berry, Drupal documentation lead: http://rocktreesky.com

53. Jean Hollis Weber, documentation co-lead for OpenOffice.org: http://www.jeanweber.com

54. Jim Campbell, documentation lead for xfce desktop environment: http://j1m.net

55. Sarah O’Keefe, Scriptorium

President of Scriptorium Publishing, setup in 1996 to provide editing and production services to technical writing departments. In 2002, Sarah received her Certified Technical Trainer (CTT+) accreditation from CompTIA. Her presentations at international, national, and regional conferences (including STC, tekom, and WritersUA) have consistently earned high ratings. http://www.scriptorium.com/about/people/sarah-okeefe

56. Shaun McCance, Gnome documentation lead: http://blogs.gnome.org/shaunm

57. Esther Shira Stepansky – Technical writer, Web Site Administrator (Webmaster), and content contributor to http://elephant.org.il.

58. Svi Ben Elya – Founder of Elephant.org.il in Israel http://elephant.org.il

59. Scott Able – The Content Wrangler

“Content management strategist and social media choreographer with strengths in helping organizations improve the way they author, maintain, publish and archive their information assets.”  http://thecontentwrangler.com/about-2/

Update Nov 19^th

This week’s updates take up to 66, the year I was born, so that can’t be so bad.

60. Alan Houser – http://www.groupwellesley.com & http://www.linkedin.com/pub/dir/alan/houser

61. Char James-Tanny – www.helpstuff.com & http://www.linkedin.com/in/charjt

62. Cheryl Locket-Zubak  - www.workwrite.com and www.linkedin.com/in/workwrit

63. Colum McAndrew, The RoboColum(n) blog at http://notcolin.wordpress.com

64. Joe Welinske – President of WritersUA www.writersua.com/jwbio.htm

65. Michael Hughes – user-assistance.blogspot.com

66. Paul Mueller – www.useraid.com

Honorable Mention

I’ve also added these three sites as, while they are a great resource. I’m not sure who the editor is. Of maybe there are several people involved. If you know, please tell me and I’ll update.

1.  Svi Ben-Elya and the Elephant organization http://www.elephant.org.il (Thanks Svi!)

2.  DMN http://www.dmncommunications.com/weblog (Aaron Davis and Scott Nesbitt)

3.  Le Blog d’Habib http://elhabib.fakir.free.fr (still trying to find out)

Where did this list come from?

I was preparing a report on freelance technical writers and noticed how hard it was to find technical writing sites run by writers, most were recruitment site.

So, I dug a little deeper and began to find writers here and there. There is nothing scientific in this list. It’s based purely on the websites that came up on Google, Bing and Yahoo.

Other technical writers who may not have websites, such as those involved in the STC, didn’t make the cut. Nothing personal here it’s just that I have no visibility on their contribution to the tech docs industry so it’s hard to gauge their impact.

Add Me!

Let me know who I missed – maybe you should be here – with maybe a few words about your/their role.

I’ll update this list and, fingers crossed, we’ll get it up to 100!

• Review of Groundswell – Social Media Technologies Forrester Research http://bit.ly/Lsol9 #
• RT @StanChu Facebook Developer Garage Shanghai June 27 http://bit.ly/B3rzD #
• YAK WordPress open source shopping cart. Developed by SourceForge http://ping.fm/w502b #
• Stunning Twitter Timeline – Evolution of Twitter in the last 3 years http://bit.ly/rxe2r #
• Google Insights. Web Search Volume for Social Media http://ping.fm/YRPDB #
• Why XML automation might help prevent the next financial crisis http://ping.fm/FuD63 #
• eBay Tip – How to create an effective listing http://ping.fm/Oz2am #
• LinkedIn User Guide. Get the most from this social networking site http://ping.fm/vBjfy #
• 5 Ways Your Business Can Profit From Web 2.0 http://ping.fm/ymZR6 #
• Schwarzenegger issues total recall of California’s textbooks to help state avoid bankruptcy. http://ping.fm/d8SxA #
• How to Add Color to a Kindle http://ping.fm/kQMRn #
• New blog post: Word 2003 Tip – How to Change the Background Color in a Word Document http://bit.ly/w4x5z #
• New blog post: How to Change the Windows Desktop Theme http://bit.ly/uKCgg #
• DITA2wiki toolkit lets you publish DITA content (maps and topics) to a Wiki http://ping.fm/6IhVN #
• Dutch Gov. To Tax Online Media To Bailoit Print Media http://ping.fm/z972m #
• Wired – 5 Signs Obama Is a Geek http://ping.fm/8PG8z #
• Microsoft Open XML Format SDK 1.0. New file format based on XML called Open XML Formats. MSDN http://ping.fm/NsI6I #
• Web Publishing – XDocs DITA Component CMS includes XML editor and publishing engine http://ping.fm/llvVn #
• Bing – What’s New in Version 1.1b of the Live Search API http://ping.fm/CZAxH #
• Twitter Bait – The Analytics of a Viral Piece of Content http://flic.kr/p/6z4dEy #
• The Interface of a Cheeseburger http://ping.fm/08fXE #
• Twitter Bait – The Analytics of a Viral Piece of Content http://bit.ly/EJkmx #

Powered by Twitter Tools.

Hi Folks. Thanks to everyone who sent me in links on the Darwin Information Typing Architecture . I have gathered them all in this page. 

[ad#5links]

FAQs about the DarwinInformation Typing Architecture

DITA experts Don Day, Michael Priestley, and Gretchen Hargis address the
topic architecture of DITA, tips and techniques, and general DITA
questions.

Darwin Information Typing Architecture (DITA)

Darwin Information Typing Architecture (DITA) is a system of Document Type Definitions (DTDs) and conventions for authoring and delivering technical information.

Specializing topic types in DITA
The Darwin Information Typing Architecture (DITA) provides a way for documentation authors and architects to create collections of typed topics that can be easily assembled into

 Specializing domains in DITA
This article shows you how to leverage the extensible DITA DTD to describe new domains of information

Migrating HTML to DITA, Part 2: Extend the migration for more robust results
Two part series on how to quickly migrate HTML topics to DITA, the author explains the details of migration, and shows you how

Introduction to the Darwin Information Typing Architecture

This document is a roadmap for DITA: what it is and how it applies to
technical documentation.

DITA Forum
Get answers to your questions in this DITA forum, hosted by Don Day and Michael Priestley, contributors to DITA and the papers that describe DITA and how to use it.

Generate DITA Java API reference documentation using DITADoclet

Combine DITADoclet and DITA API specialization to save time and still
produce quality API documentation directly from the Java source code

Migrating HTML to DITA, Part 1: Simple steps to
move from HTML to DITA

Get a quick start with DITA using available HTML topics Document options Document options requiring JavaScript are not displayed Free software for rapid results 

Implement a DITA publishing solution without
abandoning your current publishing system investments

XML-based information architecture for learning
content, Part 1: A DITA specialization design

Can topic-based DITA XML provide the basis for developing an information architecture for single-sourced

Why use DITA to produce HTML deliverables?
This article explores advantages DITA provides for producing HTML content

Tip: Easy command line processing with the DITA
Open Toolkit
The DITA Open Toolkit can transform your DITA files into a wide
variety of output types. When you first install it, it’s easy to get the
impression that you need to know Ant well to use it, but you can pack most of its available options into a single Java(TM) command line

An XML-based information architecture for learning content, Part 2: A DITA content pilot
Find out how topic-based DITA XML can provide the basis for developing an information architecture

Transform Eclipse navigation files to DITA navigation files
Eclipse navigation files to Darwin Information Typing Architecture (DITA)
format.

Design patterns for information architecture with DITA map domains
The Darwin Information Typing Architecture (DITA) provides maps for
assembling topics into deliverables. By specializing the map elements, you can define a formal information architecture.

DITA topic specialization
Darwin Information Typing Architecture (DITA) topic specialization is and
the syntax

Subject classification with DITA and SKOS
Use a DITA specialization to manage the subject matter of your document
content

Transform Eclipse navigation files to DITA navigation files
This article provides an XSLT stylesheet for converting Eclipse TOC files to
DITA map files.

Generate DITA Java API reference documentation
using DITADoclet and DITA API specialization
Automatically create reference documentation from Java source with DITA API specialization

[ad#5links]

Technical writers often have a degree in English, technical writing, the technical field for which they are writing, or a combination of these.

It is most important that they have enough expertise to understand their audience’s background and needs.

For example, writers who develop documentation for software APIs, microcontroller operation, and other technical subjects are often paid more than those who write guides for a nontechnical audience (for example, how to use email), because it is difficult to find good writers with advanced technical knowledge.

[ad]

After the documentation is written, it is normally reviewed for accuracy by one or more “subject matter experts” (SMEs).

Technical Writers Software

The most popular technical writing software includes:

• Adobe Acrobat
• Adobe Creative Suite
• Adobe FrameMaker
• Adobe RoboHelp
• AuthorIT
• Chm2web
• Corel Paint Shop Pro
• DocBook
• Interleaf
• MadCap Software
• Microsoft Visio
• Adobe Photoshop
• Microsoft PowerPoint
• SnagIt
• Microsoft Word
• XML editor

What is Technical Communication?

Technical communication is the process of conveying information about technology to an intended audience. A technical communicator is a person whose job involves technical communication.

Roles in the Technical communication industry include the following job titles:

• Technical writer
• Technical editor
• Information architect
• Usability expert
• User interface designer
• Technical artist
• Technical trainer

The technology can be of any kind, including the sciences, high technology including computers and software, consumer electronics, and so on.

Role of Technical Writing

Technical communications are created and distributed by most employees in service organizations today, especially by professional staff and management.

Effective communications require quality content, language, format, and more. The entire point of communications is to disseminate information; this is where written content comes in. To present the appropriate content, it is imperative to understand one s audience and writing purpose.

If a document does not communicate the information that the writer intends and what he or she wants the reader to understand, then the communication is meaningless.

The writer has an interest in making the extra effort: Looking credible is as important as being credible and getting results in business.

Respect and credibility of the writer/speaker are integral to effective communications. Readers will not trust the information from an author if they do not believe that author is a valuable source of information or the purveyor of worthwhile ideas.

Here are some tips for interviewing technical writers, for example, if your company needs to hire a contractor to write some documentation for your next release.

I’ve worked on both sides on the fence, (i.e. went to lots of interviews and also interviewed applicants for roles our Publications Dept) and picked up a few things in the process.

Hopefully, these will be of some help.

[ad]

A Technical Writer is someone how writes technical documentation for a piece of software, for example, a User Guide or a System Administration Manual.

They are responsible for writing text that is accurate, readable, accessible, and helpful to its intended audience.

Most companies use assessment tests to determine the skill level of potential employees.

Download Technical Writer Assessment Tests here:

http://www.klariti.com/Technical-Writing-Tests/index.shtml

How much time should be allotted to complete an assessment test?

I’d suggest 1 hour at most. 45 min should be enough.

More experienced writers will race through it, while others might deliberate over those tricky questions until absolutely sure.

Nonetheless, 1 hour should be sufficient time for most to complete the test.

Also, by allocating this amount of time to the test, you are also emphasizing its relative importance. If it were a simple 10-minute quiz, it wouldn’t carry the same weight.

Here’s a suggested approach for administering the test:

When advertising the vacancy, highlight that an evaluation test is part of the assessment process. By saying this upfront, you weed out under-qualified writers who know that they would not pass the test.

When scheduling the interview, remind applicants of the assessment test and to ensure that they arrive on time.

1. Explain to them what is involved, for example, that there is X number of questions on grammar, procurement, technology etc. This demonstrates your company’s professionalism as you are helping the applicants to prepare for the interview. In turn, it would be unprofessional to spring the test on applicants when they turn up and catch them by surprise.

2. Completing the test take about 90 minutes and some of your applicants may have other arrangements to consider, such as day-care, commuting etc.

3. When they arrive, interview them first and then do the test. If they are unsuitable for the position, you can cancel the test and say that it’s not necessary at this point.

In the interview ask them about:

• Technical Writing software they have use and which products they prefer to use.
• Note if they have a preference/bias towards a specific platform
• Ask why they prefer one Technical Writing tool over another, for example, why do they prefer Adobe RoboHelp over MadCap Flare?
• Ask for examples of how they solved problems. This helps get a handle on how they interact with other members of the Technical Publication Dept.

About.com has some sample questions for holding interviews:

http://humanresources.about.com

Different Types of Questions

Use different types of questions when interviewing prospective employees.

• Behaviors – about what the person has done or is doing
• Opinions – about what they think about a topic, for example, the rise in video as a tool for technical communications
• Knowledge – ask specific questions to get facts, for example, what version of Adobe FrameMaker do you use?
• Background/demographics – ask standard background questions, such as education, training to develop a profile of the applicant and also to cross-check their resume

Sequence of Questions

• Ask questions about some facts. This approach encourages respondents to relax and engage in the interview.
• Ask questions about the present first.
• Then discuss the past or future. It’s easier to talk about the present and then work into the past or future.
• Close by allowing respondents to provide other information they prefer to add and also give their impressions of the interview. More assertive types will have suggestions/opinions and express themselves more confidently.

Wording of Questions

• Use open-ended questions.
• Avoid Yes/No questions. Let the applicants choose their own terms when answering questions.
• Stay neutral. Avoid wording questions that might influence their answers, e.g. showing a prejudice towards a specific platform or development environment.
• Ask questions one at a time.
• Be careful asking “why” questions as this may make the person to feel defensive, e.g., have to justify their response/feelings.

Conducting the Interview

• Ask one question at a time.
• Remain as neutral as possible. Avoid showing strong emotional reactions to their responses.
• Encourage responses with occasional nods of the head, “uh huh”s, etc.
• Be careful when taking notes. For example, if you start to write feverishly, it may appear as if you’re shocked with the answer, which is likely to influence the following answers. Likewise, if you stop taking notes it implies that you’ve lost interest.
• Move from topics to topic, e.g., “ok, we’ve been talking about Adobe FrameMaker and now I’d like to move on to Structured Authoring.”
• Remain in control of the interview. Stop respondents from straying to other topics, rambling, or turning the tables on the interviewer.

Starting the Written Assessment

For those you want to assess, do the following:

• Give them a pen and paper (always helps). Some people like to sketch or keep notes when writing.
• Glass of water or coffee.
• Find a quiet room with a PC or laptop.
• Give them a printout of the test. Hardcopies are often easier to read than words on the screen.
• Walk through the test so that they understand what is required.
• Encourage them to ask any questions so there are no misunderstandings.
• Tip: Remind them when the test will finish.
• Once they are ready, leave the room and let them do the test.
• After 20 minutes, drop in to see how they are doing. The point here is not to monitor them, but to see if they genuinely need any assistance.
• After 60 minutes return, stop the test, and print it out.

At this point, I d suggest that they have a break so that you can score the test or let them know that you will call them tomorrow with the result.

This may be the most practical approach if you plan to hold a second interview.

If you want to do it the same day, then get the printout and go over the scores. As everyone likes to know how they performed in a test, walk through the results and discuss them with the applicant.

For example, if they scored low in one section, ask them how this area could be improved.

Finally, thank them for taking the time to do the tests and hope that they have gained from it.

Download Technical Writer Assessment Tests

Full URL: www.klariti.com/Technical-Writing-Tests/index.shtml

The Darwin Information Typing Architecture (DITA) is one of those topics that get mentioned in the tech writing community. Over here in Shanghai I’ve had a few meetings with companies wanting to get a handle on what’s involved and some URLs for them to look at.

I thought I’d share these with you. Many are from the IBM site as it is committed to the Darwin Information Typing Architecture (DITA) and is one of the drivers behind OASIS. If you know of any more, please let me know.

[ad]

• Specializing topic types in DITA article (developerWorks, updated September 2005).
• Read Erik Hennum’s article Specializing domains in DITA, which shows you how to leverage the extensible DITA DTD to describe new domains of information

Of all the technical writing tools I’ve used over the years, Epic Editor was probably the most impressive, especially when it came to doing tech documents that involved DocBook and Dita.

It was difficult to learn – no point pretending otherwise – but once I got the hang of it, I used it non-stop for over 2 years. Then I switched companies are haven’t had the opportunity to use it again. With that in mind, here is a brief intro to EPIC Editor, Ivan’s favorite XML Authoring Software!
[ad]

What type of document types does EPIC Editor support?

First up, let’s define a document type. According to EPIC it “refers to a collection of files that together create an application for creating and publishing documents.”

Examples of different document types include:

• Schema or DTD
• Stylesheet(s)
• Sample and template instances
• Configuration files
• Programming files that further customize the authoring or publishing environment

What document types are available in EPIC?

EPIC Editor supports the following types:

ATI XML DocBook — version of the DocBook DTD extended to provide profiling and equation editing.

• ATI Simplified XML DocBook Article — extended to provide profiling and equation editing.
• ATI Very Simple XML DocBook Article is a schema-based (.xsd) XML document type based on the ATI Simple XML DocBook Article. This document type has no DTD.
• ATI Catalog is an Arbortext-developed document type, based on DocBook 4.0, for catalog applications.
• Article is an article format based on ISO 12083.
• DITA Concept, Reference, Task, and Topic — the primary categories used for technical documentation.
• Book – book format based on ISO 12083.
• DocBook V4.0 – used for computer software documentation.
• News Release – format for preparing news releases.
• Correspondence – for business letter or memo format with several styles to choose from.
• General Purpose Document  - reports, books, and other types of documents.
• ATI-MIL-M-38784C – CALS standard document type.
• HTML V4.01 – for publishing information on the web.
• XHTML V1.0.
• Free-form XML – for creating valid XML documents that do not have schema or DTD declarations.
• ASCII  - standard unformatted text character set.

How does it work?

The interface is simple and lets you get at the XML tags very easily.

This screenshot shows the results of a test on the clarity of the document (ie its readability) and the number of words.

Next is the toolbar.

This offers a range of features that should keep most all Technical Writers satisfied if they want to develop nice, compliant XML and DocBooks.

Note that you can create tags, split sections, insert tags, and check their integrity.

EPIC Editor won’t let you add tags if they are in the wrong sequence. It this sense it can be very unforgiving – but it is simply trying to retain the integrity of the underlying code. Once you understand how XML works, it gets much more intuitive.

You can also import text files from your PC and add them to the document set.

Once you have the document ready, you can compile it to Windows Help or transform it to:

• ASCII
• DITA
• Docbook source
• XHTML

You can also add entities and prolog definitions, but this is more for advanced users.

Tip: you can also select part of the text and validate it only.

Here you can insert markups into the content, usually as tags.

Preferences

You can configure it in different ways. For example, you can ask it to show Attributes, Comments, and Tag prompts. Whichever suits your style of working.

This gives you an idea of how it checks the xml code. Work your way through the errors and fix each one after reviewing it.

Like I said, I haven’t used this for a while. Let me know if you’ve used it recently and seen any changes.

How does it compare to other technical writing tools you have used?
[ad]

In a recent survey, Scriptorium Publishing found that a majority of technical writers will be working in a structured authoring environment by 2010.

Structured authoring is a publishing workflow that defines and automatically enforces consistent organization of information. Implementations are generally based on Extensible Markup Language (XML).

[ad] 

“Most of our consulting projects involve XML,” said Sarah O’Keefe, President, Scriptorium Publishing. “This survey shows that our anecdotal experiences, such as the importance of change management, match the industry situation.”

The survey, conducted in early 2009, had more than 600 responses.

Participants cited content reuse, document consistency, and cost/effort of developing content as the primary factors driving them into structured authoring.

The Darwin Information Typing Architecture (DITA) standard was the dominant standard employed.

40 percent of existing implementations and approximately 60 percent of in-progress and planned implementations are based on DITA.

Implementations were generally quite successful.

90 percent of respondents with completed implementations reported that they had improved document consistency.

86 percent were successful in content reuse, and 70 percent reduced the cost and effort of developing content.

When asked about implementation problems, 37 percent cited difficulties with project management, including “failure to plan” and “insufficient analysis.”

“The survey validates our current methodology,” said O’Keefe. “We establish goals and metrics long before any technical work begins.”

Change management was a significant concern. Of the 16 percent who did not plan to implement structured authoring, one third cited the inability of the staff to adjust to a new authoring environment as a factor.

Staff turnover was also a problem for nearly 30 percent of past and nearly 20 percent of current implementations.

The survey data indicates that private, customized training improves outcomes by increasing the percentages of respondents who achieved their goals. Interestingly, private training also correlated with change resistance.

The 56-page report is available at  www.scriptorium.com

Emma Hamerm, Senior Consultant at eHamer Associates Ltd, looks at the common fears around moving from unstructured to structured content, (and needing to learn about DITA and XML – which frightens many people more than they’ll admit to). Emma will explore some similes and metaphors that will help us understand the impact of these new methods and technologies on our way of working. Along the way, she will look at the root causes of resistance to change, and help break through self-imposed limitations, by reframing the challenge of change, and focusing on long-term benefits. Duration: 60 minutes

In this webinar you will learn:

• to look at your situation from a different perspective
• tools and techniques to recognize emotional responses to change and their root causes
• simple strategies to help yourself and your staff and colleagues through the transition to a new way of working
• how to use narrative and dialogue to surface hidden tensions and fears and deal with them honestly and openly

Learning to Love Structured Authoring

Syntext has released a free edition of its XML editor.

This is designed for technical writers who work with DITA, DocBook and other common XML formats. To reduce time from the authoring process, composite documents are rendered using XSLT and XSL-FO to achieve a print-like appearance.

[ad]
The XML editor supports Entity and XInclude editing, along with
drag-and-drop and instant validation against XML schemas.

You can publish content to multiple channels in a variety of languages, with support for multilingual spell-check.

Serna Enterprise adds drag-and-drop from Microsoft Word and web
browsers, along with support for large XML documents. Users can insert and edit DITA constructs including conrefs, xrefs, related links and topicrefs.

The enterprise version also integrates with publishing engines,
along with support for enterprise configuration and customized APIs.

Serna Free is compatible with both Windows and Mac platforms.

The Enterprise edition carries a price of $560.

Here’s a roundup of some of this week’s news. Next week, I’ll add more info on upcoming XML authoring software releases and the new Google Wave platform.
[ad]
Adobe launches Flash Catalyst tool for rapid UI design

Adobe launched the beta release of Flash Catalyst, a new authoring tool that aims to accelerate the development of rich user interfaces with Flash. The authoring tool is a response to growing demand for more polished enterprise applications. It is intended to complement Adobe’s Flex development tool, which the company has rebranded as Flash Builder.

http://arstechnica.com

Google Docs now supports MS Office 2007 file formats

Google added support for Microsoft’s Word and Excel 2007 default file formats to its online Docs office suite. Support for PowerPoint 2007’s file format remains out in the cold. The firm has added .docx and .xlsx to the list of file formats Google Docs accepts for uploading documents.

http://www.theregister.co.uk/

How to Write Release Notes?
Our partners site, Klariti.com, released a series of articles on how to write release notes. “Release Notes cover what’s new, download and installation instructions, known issues and frequently asked questions. Creating Release Notes is fairly straightforward. Create a Release Notes template and re-use it on each release.”

http://www.klariti.com/release-notes-templates/how-to-create-release-notes.shtml

Jing Pro Released to mixed reviews
Techsmith, the makers of Snagit and Camtasia, two of my favorite technical writing tools, released a premium version of Jing, it’s online screen capture software. Feedback was mixed from the tech writing community.

Official Jing blog here: http://blog.jingproject.com and our review over
http://www.ivanwalsh.com/2009/06/review-jing-pro-–-record-hd-quality-videos-for-youtube/

5 Things I Want to Know about Project Natal

Microsoft released Project Natal, a motion sensing device that allows you to control video games and Xbox 360 menus with your body instead of a peripheral controller. Natal gives you voice and full-body motion control over your on-screen avatar using an RGB camera, depth sensor, multi-array microphone, and custom processor running proprietary software. Microsoft released the Project Natal software development kit to game makers who want to incorporate Natal functionality into their products.

http://www.pcworld.com

Hulu Desktop for Mac, PC

Hulu Labs lets you play with new products and services as they are almost ready for prime time. Among the new toys of everyone’s favorite piracy-busting online video service is Hulu Desktop, a bona fide client for the service running on both Mac OS X and Windows computers. Hulu Desktop delivers Hulu straight to your desktop with no browser required (though you will need Flash installed). Hulu Desktop is wrapped with a media-center-like bow, with a customized “lean-back” UI that can run full screen and even respond to Apple Remotes and Windows Media Center remotes.

Microsoft select St. Paul for Silverlight Offices

Gita Sitaramiah reports that Microsoft has leased space at Wells Fargo Place in St. Paul, for a software development office. The tech giant had also considered locating in Minneapolis, where it currently is operating in temporary quarters. Initially, Microsoft is leasing around 12,000 square feet of space on the 24th floor of the Wells Fargo tower, employing 26 people at the start. The St. Paul office is a key part of Microsoft’s intent to build around Silverlight, a Web browser application that competes with Adobe Flash.

http://www.twincities.com/ci_12511706?source=most_emailed

Review of Groundswell – Winning in a world transformed by social technologies

Groundswell was our book of the week and well worth a look if you want to get an insight into how social media works on a business level. In other words: how to make money from social media. Customers are writing about your products on blogs and recutting your commercials on YouTube.

They’re defining you on Wikipedia and ganging up on you in social networking sites like Facebook. These are all elements of a social phenomenon — the groundswell — that has created a permanent, long-lasting shift in the way the world works. Most companies see it as a threat. You can see it as an opportunity.”

http://www.ivanwalsh.com/2009/06/review-of-groundswell-winning-in-a-world-transformed-by-social-technologies/

Why Google Squared Makes Bing Look Good

Google Squared is a specialized search engine that creates meaningful data from large data sources and lets you compare this information by adding different attributes. Think Excel+Wikipedia+Search Engine = Google Squared. This is not Google’s finest hour by any means. Take a look at some of the results it produced.

http://www.ivanwalsh.com/2009/06/google-squared-confirm-that-richard-nixon-was-a-quaker-obama-is-a-zombie-president/

Linux/Java-based Android platform to the MIPS architecture

Technical writers with an interest in Android and open source may be interested in this. Embedded Alley completed its port of the Linux/Java-based Android platform to the MIPS architecture. The Embedded Alley Development System for Android-based Devices initially targets devices ranging from set-top boxes (STBs) to industrial equipment running the MIPS-based RMI Au1250 processor. The Embedded Alley Development System for Android-based Devices is available now. http://www.linuxdevices.com

DITA webinar
FierceContentManagement are putting on a webinar on Thursday June 11th at 2:00 pm ET called Using DITA to Streamline Your Workflow. The webinar is sponsored by Just Systems and features Gilbane Group analysts and DITA experts, Bill Trippe and Dale Waldt.

http://www.fiercecontentmanagement.com

[ad#5links]