Author-it: HTML filenames

November 14, 2008

Margaret on the Author-it User Forum list wanted to know whether to use the auto-generated HTML filenames for her output (e.g. 1234.htm where 1234 is the Author-it object code ID number), or add her own ‘logical’ filenames to each Author-it topic object so that she gets filenames like printing_a_page.htm. She particularly wanted to know whether it matters if there are both in the Publishing folder, and whether it affects the way the Help works.

My response:

For HTML output, you’ll get <object_code.htm> unless you have explicitly entered a file name on the topic’s Web tab.

Having the filenames or object codes (or both) is neither here nor there as far as Author-it is concerned. However, you might want to consider your users, your deliverables, and your time!

If your output is going on to the Web (not internal), then a named file may be more readable. That said, if the output has a TOC/navigation pane the user tends to only ever see index.htm anyway, no matter which topic they’re reading.

CHMs don’t care about filenames—everything is compiled into one file anyway. Other HTML outputs—see the info for ‘Users’ above.

To use filenames you have to manually decide on and add a filename to every new topic. There are a few issues to consider with this:

  1. Filenames should not contain any spaces, unless you are ABSOLUTELY certain that the HTML files will only ever live on a Windows machine/host server.
  2. Filenames must be unique.
  3. If you duplicate a topic, you must remember to delete the duplicated filename and replace it with another, unique one. Otherwise you will get at least one topic that’s published as a blank topic where two or more with the same filename exist in the same book.

When I first started using Author-it I was still hung up on unique file names for topics. I liked the look of them in a folder list, they had meaning to me, etc. However, the overhead of maintenance became something I didn’t want to continue, so I went back to using the default object codes. And you know what? It really didn’t make any difference at all—except free up a lot of ongoing maintenance time for me. Not one user ever noticed or complained.

One comment

  1. I actually need to create our file names where I work. Our developers and testers typically check the HTML help folder for our applications for the following reasons:

    1. To quickly double-check to make sure that pages for new window-sensitive help topics are in the latest output. If they’re expecting to see, say, orderform.html and don’t, then they know they need to check with me.

    2. To troubleshoot problems between their configuration files and my help files before raising a red flag with me. More than once, they’ve ascertained that the problem was a typo in the config file (e.g., odrerform.html instead of orderform.html) and not a problem with the help output.

    Granted, the help files I maintain now are smaller than ones I’ve maintained in the past. The practice is manageable, and the overhead involved simultaneously attends to some QA checkpoints we have, so the effort is easy to justify.

    In larger systems I used to maintain, in which there were 800 topics or more, I’m not sure how I would have handled this issue had I been using AIT and not RoboHelp.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: