The Logical Blog by IconLogic

Using Bold... and Other Tech Writing Conventions

Last week I offered my opinion on the proper use of bold and italics in e-Learning. I wanted to know your opinion. John Laflin, PhD, Professor of English at Dakota State University, Madison, South Dakota was kind enough to offer the following:

---

I teach courses in software documentation. In each student project I insist that a list of manual conventions be included. (It’s absolutely incredible how many software, hardware, and peripherals manuals do not list any conventions.)

Students are fond of placing any user-generated text in “quotation marks” – e.g. Now type “the quick brown fox jumped over the lazy dog.” I always counsel against this practice as the user should not actually type the quotation marks, and the writer has to tell and remind the user not to do so. The period at the end of the sentence is another concern, but I can get to that later.

So I advise either bold faced type or a color or even a different typeface, such as “Courier” for those bits of text that a user should type. These font changes are not under the user’s control, so there would be little if any confusion about what to type. Line breaks are also useful here, as a writer can minimize confusion by placing a Line Break (and not a paragraph break) before the “and” in the following example:

“Now type: the quick brown fox jumped over the lazy dog and Press [ENTER].” Some users will be bound to keep typing unless the line ends after the word “dog.”

I certainly have no problem with using bold to indicate menus or whatever; however I would also suggest that the convention help make the writer more efficient. If the writer has said in a conventions page that “words in bold-faced type indicate the names of menus,” the writer does not need to say “Click the File menu.” Instead the writer only needs to say “Click File” as the bold type actually substitutes for the words “the” and “menu.”

Now as for those pesky periods: I allow my students to omit periods that would normally be required when they fall at the ends of sentences that a user needs to type. As with the example above, the quick brown fox jumped over the lazy dog

This sentence would normally require a period at the end; however putting a period at the end will confuse readers and it’s very hard to see whether or not a period is bold. And of course in the old days of typesetting there was no such thing as a “bold period.” Although the period in the example above is not critical, think about a web address, where a stray period could create a “404 Not Found” error.

Thanks for the opportunity to share.

---

Great stuff, John, as usual. And thank you.

Adobe Captivate 2: Trial Users Beware, Your Published Movies Will Time-Bomb!

Those of you who are putting off purchasing Captivate 2 until after your 30-day trial expires, beware. While the trial version of the software is fully- functioning, projects that you publish are not!

Say it aint so, Joe!

Sorry, it’s so. Open your project using the trial version of Captivate 2 and then choose Project > Preferences. On the Start and End tab, notice that Project expiration date is selected, and you cannot disable it. Any movies you publish will expire 30 days from the day the trial version of Captivate was installed on your computer (not 30 days from the day you published the project). Ouch!

Not to worry though. Movies you create with the 30-day trial of Captivate 2 do not expire, even after the trial period is over. If you purchase the software, you’ll be able to open the trial files and, if you check the Project expiration date, you’ll notice that the feature is off by default.

MenuBuilder: Two Problem’s That’ll Burn You

If you have HTML experience, you can take your published Captivate files and create links from your Web page to the published files. Of course, you’d need the HTML experience to proceed.

MenuBuilder offers a quick way to package your Captivate projects for distribution to your customers— without the need for HTML experience. Using MenuBuilder, which comes with Captivate, you can create a “home” page or “menu” that contains links to your Captivate projects or other links. The “home” page can serve as the gateway to your projects.

If you’ve purchased my Captivate workbooks, you already know how to create MenuBuilder projects. In that case, I won’t bore you with the details of how to create the projects. I will, however, provide two cautionary tales when working with MenuBuilder (the first tip is in my Captivate book, the second is not).

First, when creating a link to an item, make sure you select the Save file with project checkbox. If you fail to select this option, users clicking the link after you have published the project will following the absolute path to your project, such as C:\Captivate2Data\ MenuBuilderFiles\MenuBuilderExports instead of the CD or Web site where your movie are actually stored. With the Save file with project option selected, the link will instead become a local link.

Second, after publishing your MenuBuilder project as SWF files, check the target folders. I’m betting the folder will be missing a few files, mainly the skin .swf that gets published if you include a skin in your Captivate 2 movie; and the standard.js file that was discussed in last week’s newsletter. Without these two critical files, your movie will not play. The solution is a manual one, but it works. Find the skin .swf and .js files in the folder where you published your Captivate project prior to working on the MenuBuilder project. Copy the files and paste them into the MenuBuilder published project folder before uploading the published files to your Web server or, worse, burning the files to a CD.

Importing Adobe Captivate 2 Movies into RoboHelp

Fellow RoboHelp and Captivate instructor Rick Stone wrote a series of articles dealing with importing Captivate movies into RoboHelp. If you are a RoboHelp user, you will find the information very useful. In the interest of space, I have combined the articles below. You can read the full text on Rick’s site.

---

It's quite common to use Captivate in conjunction with RoboHelp in order to provide comprehensive assistance for the end user. For example, why just capture screens and type explanations, when you can just show them a movie? The movie can also contain audio!

How to insert Captivate Movies into RoboHelp

1. Right click the desired folder inside RoboHelp HTML and choose Import... from the context menu.
2. Ensure the "Files of type" field at the bottom of the dialog are reflecting HTML files.
3. You then navigate to where the files are stored, select the desired file and click the Open button.
4. At this point, the HTML "companion" page as well as the .SWF are brought into the RoboHelp project. You then treat the HTML page as you would any other HTML topic page in your RoboHelp system.

If you view a Captivate 1 movie in Internet Explorer, you typically encounter some oddness. Specifically, as you mouse over the movie, it becomes surrounded by a frame. If you rest the mouse pointer over the frame, shortly you see a "Tooltip" type of popup message that says "Click to activate and use this control".

You see this message because Microsoft found themselves on the losing end of a lawsuit and was ordered by the court to change the way Internet Explorer presents content such as Flash. The odd part of all this is that while this behavior is observed when viewing the movie using good old Internet Explorer, it performs a disappearing act if you insert the movie into a .CHM file. If you insert the movie into a .CHM file, you don't have to click to activate it. You may wonder why I think this is odd behavior. After all, Internet Explorer (IE) is the browser and the .CHM file is a help file, no?

While you would be correct in assuming they are definitely two different entities, the .CHM viewer relies on different components of the browser to display content. Thus I would think if content has an issue in IE, the same would result inside the .CHM.

Sooo, if it works just dandy inside a .CHM file, why should I care?

Well, one workaround for this behavior is to reference some external JavaScript for displaying the movie. The method the Adobe Captivate developers have implemented is to include an additional JavaScript file that is used when displaying a Captivate 2 movie. Unless you tweak things, this additional file absolutely MUST be present in order for your movie to load and play. If the JavaScript file isn't present, the movie will not play for your user! So this JavaScript file must now be included among the mix of files if you are importing the HTML page Captivate creates and adding it to your project.

There are two files involved if you are adding Captivate content to your RoboHelp projects in this manner. So as you can see, we now have at least THREE files involved.

• The Captivate .SWF that comprises the main movie
• The Captivate created HTML "Companion page"
• The Captivate created "standard.js" JavaScript file

Wrinkles abound!

Hmmm, as if this weren't enough new potential variables to toss into the mix, Captivate 2 tosses in one more, just for good measure! With Captivate 2, you may also have one additional .SWF file in the mix.

What!? How can this be?

Want to learn more. Click here to go to Rick's site and read the rest of the story...

Grammar: Using Quotation Marks

The rules for quotation marks can get a bit confusing as they are not related to logic in any way. My best advice is to always check the rule before using the quotation marks. Since we don’t use them that often, these rules are not worth memorizing; however, they are worth looking up in a reference book. Put periods and commas inside the closing quotation marks. This is the American style. The American convention for placing commas and periods inside quotation marks offers no logic. If you deal with publications from England or Australia or South Africa, the rules for the quotation mark will differ.

Here are examples of a period and comma with quotation marks:

• The letter was marked “Confidential.”
• She described her new friend as “tall,” “handsome,” and “intelligent.”

Put colons and semicolons outside the closing quotation marks. Again there is no logic to this rule.

Here are examples of quotation marks with colons and semicolons:

• I had my doubts when I heard him say, “Your check is in the mail”; needless to say, I have received nothing.
• We know what she means when she says to use some “ingenuity”: creativity wins proposals.

Use the following patterns for question marks and exclamation points at the end of a sentence concluding with a quotation:

Here are examples of quotation marks with question marks and exclamation points:

• When the quote is not a question, but the sentence is.
  
  Did they say, “We’ll help”?
  
• When the quote is a question, but the sentence is not.
  
  They asked, “May we help?”
  
• When the quote is a question, and so is the sentence.
  
  Did they ask, “May we help?”
  
• When the quote is an exclamation, and the sentence is a question.
  
  Who yelled, “The sky is falling!”
  
• When the quote is a question, and the sentence is an exclamation.
  
  Don’t ask, “Where is the exit”!
  

Use quotation marks for a direct quote, not for an indirect quotation.

Here’s a direct quote:

The forerunner declared, “My political record shows that I am the best person for the job.”

Here’s an indirect quote:

The forerunner declared that his political record shows that he is the best person for the job.

Note: Single quotes are treated the same way as double quotes.

Adobe Captivate: Caption Calculations Got You Down?

So, you insert a text caption.

You edit it just so, select your font and caption style, and then click OK.

Then you spend a good chunk of time working on the Timeline getting the timing just perfect.

And off you go to the next slide, and the next, and the next. No problems.

You play the movie. It's perfect.

But then you are asked to make a "few" editorial changes to the captions. "No problem," says you. You open a caption here and a caption there and happily make the changes.

You play the movie. And, and... it's NOT perfect. Much to your horror you discover that the timing for your edited captions has mysteriously changed. The caption on slide 2 that was set for 8 seconds is down to 4. Huh? You added text. How on Earth could adding text decrease the time? Come to think of it, how come the time changed at all? You set it to 8 seconds, and that's how it should stay.

You are not crazy. In its zeal, Captivate is trying to help you by always calculating the timing for your captions, even if you think you know better.

Want to turn that less than helpful feature off?

Choose Options > Calculate Caption Timing to turn the command OFF.

And that’ll take care of that.

No problem!