Last Modified: November 29, 2001

Writing Your Book So That it Converts Easily to HTML

Converting to HTML is pretty easy if you follow these guidelines when writing your book:

Stick to the Open Market Templates

Every component in the new Open Market templates maps to an HTML component. In fact, we designed the new templates so that they would map easily to HTML.

Don't panic if you need a component that isn't in the Open Market template. Hey, if you need a component, then chances are that others do, too. All that we ask is that you let the Template Czar create the component for you. That way, we're all on the same page.

Tag All Text

FrameMaker lets you bold and italicize text by clicking icons from the QuickAccess Bar. It is tempting to use this feature, but please don't. Always tag text; that is, change fonts by selecting the appropriate component from the font catalog.

Import All Screen Shots by Reference

When you request that an image be put inside your Frame document, Frame asks you whether you want to Copy Into Document or Import By Reference. Always choose the latter. If you mistakenly copy into the document, WebPublisher will make a screen shot of your screen shot (yep!), and the results will not be satisfactory.

For prettier results, always choose Import By Reference. Not only will the resulting HTML look better, but WebPublisher will also be able to convert your document much more quickly.

Finally, importing shots by reference seems to be a much better way to go from a documentation engineering perspective.

Store All Images in GIF or JPEG Format

All graphical browsers can display GIF or JPEG images.

Don't Create Images Larger than 60K

I'll arbitrarily set 60K as the target maximum size for an image. Please read more about this topic in the screen shots section.

GIF compresses images. So, in line art, the complexity of the image also controls the size of the GIF file. For example, gradual shading looks really cool on paper, but it may not compress very well.

Don't Embed Components Inside Bulleted Lists

Don't put paragraph components between items in a bulleted list. That is, some of you are creating lists that have the following format:

The preceding list typically comes out strangely in HTML. Although the HTML can be rigged, there is no tag in HTML that maps naturally to nonlist components between list components.

Moral: don't use bullets as headers. Use headers as headers. For example, the following shows a much better way to present information:

The following section details each of these items.

Apples

Lots of information about apples.

More information about apples.

The secret life of apples.

Bananas

Lots of information about bananas.

More information about bananas.

The secret life of bananas.

Carambolas

Lots of information about carambolas.

More information about carambolas.

The secret life of carambolas.

Create Lots of Cross-Refs Within Your Book

Create cross-refs whenever you can. Every cross-ref that you put into FrameMaker will end up as an anchor in your HTML document. (An anchor is one of those underlined blue thingys that users can click on.) Anchors are good.

Don't Create Cross-Refs to Other Books

In theory, creating cross-refs to other books is a splendid idea. In practice, WebPublisher will not be able to create hyperlinks to other books.

Avoid Footnotes

Zen riddle: What is the bottom of the page when there are no pages?

Since HTML is file-oriented instead of page-oriented, all footnotes end up on the bottom of the file instead of the bottom of the page. Not the worst thing in the world, but a little clumsy.

Footnotes are just a tad academic, doesn't one think?

Avoid Wide Lines of Sample Code

When possible, try to keep each line of sample code down below 70 characters.

Get Colorful

When writing in FrameMaker, most of us think in black and white. After all, our FrameMaker files are usually printed in black and white. By contrast, our HTML files will almost always be viewed on color screens. Live a little; add color to jazz up your images.

Avoid Page-Oriented Lingo

Page numbers have no meaning in HTML docs. It's tedious to remove them from random cross-references.

Phrases like "on the following page" also have no meaning in HTML.