I’d Rather Be Writing - Tom Johnson

[...] with the release of Flare 4, I’m giving away a free copy of Flare. See this post for details about the [...]

[...] Speaking of Flare 4, Tom Johnson is giving away a free copy of Flare 4 (full version, retail value near $900). To enter, all you have to do is leave a comment on his giveaway post. [...]

Hi, Tom. Flare 3.1 is the first HAT I’ve really used, but one of the most important features has been being able to format the CSS for both online and print. The CSS editor lets you do that by choosing a different medium in a drop-down list. That lets us create Word output without having to use a Word template or a master document. The last time I published, I spent about 1 1/2 hrs post-Flare for a 300 page document, and we’ve improved our CSS and process since so that I think even that will be greatly reduced next time.

Kristi Leachs last blog post..10 Steps for Importing Large Legacy Word Docs into Flare

One thing I want in a HAT is the ability to easily create multiple outputs. Once I set up my templates and formats, I can do this pretty easily in Flare 3, and it sounds like Flare 4 will make it even easier.

Please enter me!

A good help authoring tool must be “standards based” and have good import and export features. No tool should set itself up as the end of the line. Over the span of a career, a technical writer expects to change tools a dozen times. The perfect HAT will support that change both in importing multiple formats and in saving files into an open standard format that can be exported (or formatted through a script) to other formats.

I hope I win the contest! My company is transitioning to Flare 4 as soon as it is released.

Tom:

I am a relative newcomer to the world of HAT, and the transition from static (print) to interactive (HTML) help files was fairly brutal. In fact,after working with Robohelp for a few months, I contacted my professors @ the university to instruct them to reorganize their thinking and teaching. I wanted to make sure the other grad students would be prepared for the organization required in using HATs.

That said, I find that the CSS tools are particularly helpful when I’m working with a HAT. Also, the ability to publish both static and dynamic files from a single HAT has become a deal-breaker for me. When I think about the time and energy I wasted at first, I am truly appalled.

Finally, and perhaps most importantly for my business, I love that Flare has a built in translation program. Our company has taken on the task of creating the source documents for our global division, and having the ability to create databases of words/phrases that are specific to our industry will have a positive impact on our time. As we continue on with our translations, we can continue to add to our database, and consequently cut down on our translation costs. And when you’re talking about translations into 17 different languages, that is a significant amount of money.

[...] Flare 4 Giveway — Enter to Win a Free Copy by Commenting on This Post | I’d Rather Be Writin… Tom Johnson | September 3, 2008 | permalink Tags: flare, giveaway   [...]

Hi Tom,

For me there are three important aspects for a HAT:

1. Ability to single-source from Word documents (what most of my clients need).

2. Produce multiple outputs

3. EASE OF USE - and by this, I mean
a. An interface that is really easy to follow with unambiguous terms, and Help that defines everything
b. Minimal installation errors, including the demos; minimal corruption (none preferred), including the demos
c. Easy to customize the look and feel without having to know .php, .xml, or new .HTML code (nice things, but it gets old after a while)
d. If a special file is required for viewing, it is part of the Help system and includes an “Install me” button

I like a help authoring tool that can easily integrate with Word. It would be really nice if when importing a Word document, the help tool could automatically make all text and images formatted with a particular style conditional.

I really like the tutorials and the degree of customer service offered by Flare. The Flare representatives really care and took the time to help me through some difficulties I was having with the trial version of the software.

My big concern these days is open standards, open formats, and open licensing. While MadCap has made big strides in that direction, it’s my understanding that the Javascript in their WebHelp format still has a proprietary license, which means it can’t be used in open source projects. It also would be great if they would support output to Eclipse Help.

That said, I would not turn down a license if I won the drawing

Multiple output formats is very important.

My pet peeve - a help comment for ‘Name’ that says “Enter your name.” Well??? Last name, first name, user name? Give me a clue!

Thanks for the sweepstakes!

For me, any tool used in producing content must have a CLI (command line interface) so that it can be integrated with a lights-out build system. It should be possible for the writer to commit the source to a source control system and have a build system rebuild it at a scheduled interval.

If I had a copy of Flare, I’d evaluate it’s CLI (I downloaded a demo once, but the demo version had the CLI disabled) to see if I could use it to generate web-based help (with toc pane and search) from the combined html+xml goo required by Flare that I generated from an existing XML-based system.

For me, the most important question about a help authoring tool is how much TIME will it save me. Can I learn to use it quickly? Can I re-use and re-purpose content easily? Can I create new content on the fly?

I currently use Flare 2.5, and it passed all my time-saving tests with flying colors. Flare 4 sounds even better! Thank you for offering the sweepstakes!

One of the features that I look for (and is unfortunately hard to find) is being able to view or edit information without making ‘helpful’ behind the scenes changes to the data.

It’s probably easiest to describe this in the desired case.
Let’s say I open a file, version1.xml, view it, add a period, spell check it, and save the file as version2.xml.

Now, I diff the two files using a a tool like beyond compare.

If I’m using an editor that plays nice with the file, the only difference between version1.xml and version2.xml should be the period that I added.

If I’m using an editor that does not play nice with the file, the two files will differ in whitespace, some tags may have been added, meta-data may have been added or changed, etc.

And when will Flare output Eclipse doc plug-ins as a format?

I like to be able to easily get at the source to make edits when desired. Perfect example: Flare provides a interface to edit the styles without my having to know a thing about CSS, but because I’m experienced with CSS, it’s nice to be able to just open the CSS file and make my changes.

Features that I expect in a HAT:

- Multiple output formats (xml, pdf, Webhelp, HTML, word processing format, DITA aware, etc.)
- Modular structure (capability to build “parts” by book, chapter, or DITA map)
- Reusable topics, words, paragraphs (Flare does this)
- Flexible interface (windows are sizable, docking toolbars, and so on)
- Capability to link to “outside” files in a TOC and within help pages
- GOOD Help files*
- Local support (live person available by phone) hopefully in a US or Canadian Time Zone*
- Link checking* with an indication that there are orphan files, broken links, or files that are missing, or not used at all
- Overall spell check (for all topics in the project, not just the one that’s open)*
- Effective search and replace across the project, with native file format capability (i.e., XML and HTML code search with tags)*
- Integrated file handler and document repository that is reliable* and is provided with the software

Currently, I am working with DITA and XML. I love separating writing from formatting and creating reusable text, but otherwise I feel like I’ve time-traveled back to 1992! The functionality is just not there right now.

Many of the features available in XML DITA aware applications (those marked with a * in the list above)are not available in current tools. That means no link checking (broken, missing, not linked at all), no spell check across files, no search and replace across files, no built-in file handler. All those capabilities have to be provided by cobbling together disparate applications, some of which are shareware, and others that are open source, and have little–to no–support. Those limitations (along with learning DITA as well) have required some creativity on many a day to get the work done.

Content reuse!

My company purchased Flare 3.0 last fall for my co-technical writer and me based primarily on the criteria of cost and licensing. Several HATTs would do the job of multiple outputs and meet the other criteria that we needed for an authoring environment but our choice needed to fit our budget and allow multiple authors and source input from either Word or FrameMaker for one price. My co-technical writer has made great strides in moving our legacy documentation over from FrameMaker. I have to admit I have resisted the move from my work flow that includes FrameMaker and another tool due to release deadlines and other time consumption. But, that has to end with version 4.0. I have to move on. Having a copy I could practice with at home would definitely be an asset to my learning curve, especially after I take a training class in November.

I’d heard colleagues say good things about Flare 3, but after looking at Madcap’s website, I see some disadvantages:
- there is only a Windows version.
- like RoboHelp, you almost have to have their “server” (Madcap = “Feedback Server”) to host the help files.
- RoboHelp’s “host” server for the help files was a pain to set up with almost no documentation. Hopefully Madcap has better instructions.
- Feedback Server only runs under IIS, limiting this software to big companies with big IT Tech departments (IIS is not a “plug and play” server — it needs constant babying and security upgrades) or small companies that happen to have an IT Tech genius.
- I clicked a Madcap website online help topic — brought up their interface. Am not impressed with the font, icons, layout, and the EXTREMELY busy set of icons across the top. Hey, I’m looking for a quick answer to a question — I don’t have time to spend 15 minutes figuring out your user interface and odd icons for the online help windown.
- for the online help window, I noticed that in both Firefox 3.0 and I.E. 7, that the TOC is “cut off” on the left when first opened — you have to grab the bottom scroll bar and drag to the left to see the cut off parts.
- as a CSS person myself, gee, it would be nice to edit CSS directly, but I can understand why Madcap doesn’t let you. There are dozen’s of ways to do the same thing (depending) with CSS, and with all the “tricks, hacks” out there, Madcap would have to spend two years just writing a CSS parser. I’m sure they’ve written a simple one with basic rules, so they can spend more time developing their products.
- NICE TO HAVE: tie into a code management system, other than it’s propriety server, e.g., CVS, Subversion, and so on.

Thanks Paul.
You’ve helped a lot to better understand and appreciate Flare, with my never having used it. I particularly like that Flare will work with code management software (using a third-party tool).

Tom,

I like being able to get a job done as quickly and as painlessly as possible. Because of that, I rank ease of use among the top requirements for a HAT. I want to get in, get the job done, and get out without the need for excessive time spent messing with the tool just to get whatever form of output I’m after. Personally, I think many HAT’s fail on this point.

Flare’s Webhelp output does not require Feedback server, It can be hosted on any webserver. If you want feedback for your project you can have feedback server or Servce, and the feeback server doesn’t have to be on the same webserver as your website,

Feedback server could be installed onto an IIS server, and your various websites can be anyhere and send the data back to Feedback server. The beauty of Feedback server is that it can take the data from anywhere, from your end users desktops, or from a webserver, It will even take data from HTML help or Dot Net help.

What I look for in a HAT is intuitiveness. Although I write help systems for a living, I don’t want to actually have to refer to one!

Hi Tom:

I’ve always wanted to try this software. I hope I win!

Usability, flexibility, support, reliability, integration or compatibility with other tools. Intelligent Design (not the anti-Darwinian sort).

Am switching between tools frequently, so I don’t want to have to get into a different head space when swapping from one to another.

I need to have confidence in the output that is delivered to the clients.

I want flexibility without having to delve too far under the hood.

I don’t think I could list one, or even many features that are the most important without writing a huge essay - they all are!

I just downloaded my first copy of Flare, and I’m so impressed with the improvement over my previous HAT. After reading Paul Pehrson’s review, I’m looking forward to Flare 4.0.

I read your preview and I’m really excited about the improvements. Flare 3 was already a great product, but v4 has a lot of improvements that I’m looking forward to trying.

The biggest one, for me and my department, is the straight to PDF option with the page layouts. I spend hours doing this now (not with Flare) and the thought of getting a decent PDF right off the bat, makes me smile.

I also like the global project files. We have some standard corporate frontmatter stuff and it changes periodically. It would be nice to just link in to a single location.

If Flare succeeds in making single-sourcing a simple process, it might make our CMS/XML team jealous.

In every of the (many) software development groups I’ve worked with, time-to-market is critical and for this reason and many others the technical writing part of the project is shortchanged on time.

A HAT user interface that is intuitive saves valuable time when time is at a premium.

My primary needs in a HAT, are that the HAT:

* Produces multiple outputs.
* Offers clean import from Word.docs.
* Allows for single sourcing.
* Has an intuitive interface, and is easy to use. I don’t want the tool to add extra steps, as my deadlines are aggressive.
* Contains a good help system, so I can find relevant information quickly.

One feature that I can’t live without is conditional text. It’s absolutely necessary for managing the slightly different product types that product management always insists on creating.

I like Flare because it rhymes with Care Bear

Back when it looked like RoboHelp would be a tool of the past, we went through the trouble of defining what our replacement Help Authoring Tool would look like, and these are the requirements we came up with:
- Must be able to import existing RoboHelp projects with ease and require little or no rework post-conversion.
- Must include a WYSIWYG editor (most of our writers had limited HTML experience).
- Must be able to produce multiple outputs (HTML-based Help, DOC, PDF, etc.)
- Must be able to preview the output and render the preview accurately.
- Must be able to incorporate addtional media (Sound files and video files - WAV, MP3, SWF, AVI).
- Must support multiple image formats (GIF, JPG, PNG, etc.).
- Must have the ability to create and/or customize skins for the Help output.
- Ability to use the same single sourcing process we developed around RoboHelp.
- Must support the use of our CSS and Help template file, or at least the ability to recreate them.
- Must have the ability to use conditional build tags at both the content and topic levels.
- Include a multi-file find and replace utility.
- Must be compatible with Windows OS (2000 through Vista).
- Must include a built-in utility for resizing images. A screen capture feature would also be nice to have.
- Must support multiple authors on a networked environment.
- Translation of output to multiple languages would be a nice feature to have.
- Project management and reporting features would also be nice to have.

Another very important thing for my favorite HAT would be: Shortcuts (like Alt+Ctrl+X,y) that can be used for all functions and styles and formatting and … – and that can be defined by my own.
I am very glad that I left Word behind in most of my projects. But I am missing Word’s flexibility and potentiality of defining and using shortcuts both in Robohelp X5 and in Flare 3.1 …
Best regards
Siggi Gröf
Technical Communicator

Key characteristics I look for:
-Ease of use
-Printed outputs should require minimal additional work after being produced
-Provide good value for money
-Able to handle large projects without performance degradation
-Good/large community for support

Tom

Absolutely the most important feature in a HAT would be multiple outputs from a single source. It ensures the professional feel that consistency of content and formatting gives, as well as accuracy of all content since any updates need only been made once, in one place.

Jasmine

Jasmine Andrewss last blog post..Rainy Days, Books, and Google Analytics (or From Here to There)

Like many of the previous posters have already mentioned, the most important features I would want in an HAT would be:
1) flexible imports and exports
2) customization ability
3) user-friendly UI
4) short learning curve

I haven’t used Flare before but I am going to try it out. Someone mentioned that it has a translation tool which may be useful in a project I am working on.

Question: “In the comments below the post, explain what you feel is an important feature for a help authoring tool and why. Your answer can be short (one sentence), or you can write a novella.”

Hi Tom,

The most important feature of the help authoring tools is the output that is the deliverable - I echo my fellow writers in that thought.
This can be followed by the features that:
- Enables effective content re-use thereby saving time and money.
- Supports importing content from different formats
- Provides support to plug in content from multiple authors in a project
- Facilitates tracking the status of project at each phase using reports

I read your post on Flare 4 features and wanted to have a copy to test all my projects and slowly move to a one-stop-solution.
Please include my name in the Flare give-away lottery.

Thanks
Sri

A good HAT with multiple output formats should allow the writer to tune his output for a particular medium without regard to any other mediums. In addition, the flexibility and versatility to produce clean, good looking content is incredibly important since most writers no longer submit their output files to a typesetter for placement on a Linotype.

As others have said there are lots of important features (multiple outputs, flexibility etc) but for me I think it has to be the interface - friendly and easy to use. So many of the features are ’standard’ now that it’s how easily and quickly I can get it to do what I want that’s important.

Nice contest! Let’s all hope i win

The help system should be intuitive and must allow me publish to multiple formats easily. It should have a content management system or should be easily linked to a CMS. I liked Robohelp a lot, but it lacked CMS and versioning. It would be good if a HAT can provide all these.

Someone already mentioned this, but being able to port documentation to various outputs is central to a HAT, for me–including being able to port it to Word documents. I’m amazed, in some ways, that the porting-to-Word stuff is so useful, but I expect it will be fore a while.

Thanks for the info, and the contest!

jeffs last blog post..Men’s Story Project

As a complete ‘newvie’ to Flare I am quickly finding my feet. Of particular interest is the multiple outputs from a single source. Can’t wait to get my hands on version 4.