Chapter 1. Planning and Organizing Strategies

CONTENTS

•  Saving Time with Templates
•  File Management
•  Adding Graphics from Another Application
•  Summary

If you planned on writing a technical document, you wouldn't just start writing it without an outline. If you were going on a long road trip, you wouldn't just jump into your car without a map or some prior knowledge of how to get from point A to point B. Whether you're writing, traveling, or doing a multitude of other activities, planning ahead is essential to the success of what you are trying to accomplish.

The same rule applies to working on Framemaker projects. The point of using a robust program like FrameMaker is to automate routine documentation tasks and, therefore, simplify the production process. Without some up-front planning, however, you'd be stuck later in the project frantically trying to correct problems that you could have avoided in the first place.

This chapter presents some things that you should think about before you start a FrameMaker project. I explore a plan to organize files by using templates to ensure consistency across documents, working with a group, and what you need to know about imported graphics. Keeping projects streamlined and organized is a good foundation for a successful project.

Saving Time with Templates

Templates save you time and provide the consistency that's necessary between documents. In a nutshell, a template consists of preset document formats and features that are used as a basis for other documents. Therefore, formats and features do not have to be re-created every time you begin a new document.

Working through a document's formatting and feature requirements in advance helps you to establish document-publishing standards that you need in order to create FrameMaker templates.

After you create document templates that you can work with, use the same template for each new document. For example, say that you're creating a book with 20 chapters. After you create a template for one chapter, you can use that template for each new chapter. This ensures you a consistent format throughout every chapter in the book.

Back to Basics

Use File > Import Formats to import new formatting information to one or more documents.

If you decide to make design changes to the book, you can incorporate those changes into one document file and import the new formatting information into other document files that use the same predefined formats.

Anatomy of a Template

If you dissected a typical FrameMaker template, you would end up with this list of features:

• Page layouts

• Paragraph formats

• Character formats

• Table formats

• Color definitions

• Document properties

• Cross-reference formats

• Variable definitions

• Math definitions

• Conditional text settings

Although you might not need each feature, keep them in mind while you plan and go through the decision-making process for your own FrameMaker templates.

Planning Templates

Taking the time to plan your FrameMaker templates is worthwhile. For starters, consider the overall ingredients of your publication before you delve into the details. For example, you might ask yourself the following questions:

• Is there a table of contents or an index?

• Will I need chapter and appendix templates, or just one or the other?

• Does my document include a preface or a title page?

After you understand the ingredients that you want to include in your publication, the next step is to determine the document's design and plan the features that each ingredient includes. For example, a template for a title page probably won't include numbered paragraphs, but a chapter template would.

With your overall goals in mind, develop a list of features that you need for each ingredient that makes up your publication. You might ask yourself the following questions during this planning phase:

• Is automatic numbering part of my document's overall features?

  If so, you must plan out what type of numbering schemes you want to produce in your documents. For example, will you plan for numbered lists that include numbers or alphabetic items? Are just the chapter headings numbered or is military numbering style preferred?

• Will tables be included in my documents? Will they include rules? How about table titles?

• Will running headers and footers be included? If so, of what are they comprised?

  For example, if running headers or footers include each chapter's title, you have to consider creating Running Header/Footer variables. If they include the document title, you should consider creating user variables.

• Do you plan to use cross-references? If so, what types of cross-reference formats?

Note

Download FrameMaker template packs at http://www.adobe.com/products/framemaker/.

After you understand what features your FrameMaker templates need to include, you can create templates from scratch or use an existing FrameMaker template (available from Adobe) and modify it for your own use.

The Inner Workings of a Template

Every FrameMaker document file is also a template. A document file and a template are one and the same. Any FrameMaker file that you open can also be used as a template.

If you use a content-filled document as a template, a new, untitled document opens and includes the complete contents of the source document file. You must delete the contents of the new, untitled document at that time.

To use any document file as a template, follow these steps:

1. Select File > New > Document.

   The New window appears.

2. Navigate to the location on either your hard drive or file server and select the FrameMaker file that you want to use as a template. The filename is inserted into the Use Template field.

3. Click New.

   A new, untitled document opens with the same formatting features of the FrameMaker file that you used as the template.

Test, Test, and Test Again

After you establish the features of your FrameMaker templates and incorporate these features into a document, testing your template before you begin writing is a smart idea. Try out the template with dummy text to test running headers and footers, numbered paragraphs, or any other features that you created. Each feature should work under any circumstance.

If you have the urge to forgo testing your templates, keep in mind that once most of the document is finished, it's more difficult to solve template problems. If you are revising an existing template, go through the same testing process. If problems occur and you import that problematic template into your existing documents, your problem increases tenfold.

Testing and focusing on the logistics of how the template should work must be your first priority when you create or revise templates.

Keeping Your Documents Consistent

Documents do not magically stay consistent, even when you use a slick template. If you're working on a document with your coworkers, everyone must participate in maintaining consistency across documents. For example, suppose that you are working on a FrameMaker project with six coworkers who are contributing to the documents as authors. Although you base each new document on a single FrameMaker template, at any given time, different people work on several documents in various stages. While every person works on a document, they might want to make a slight change to a paragraph tag, a cross-reference format, or some other feature. They might think, "It's just a small change; it's not a big deal." However, it quickly becomes a big deal after you compile the book, which is made up of all these documents. All the little changes that you or your coworkers incorporate makes it difficult to maintain the necessary consistency across documents.

Therefore, it's up to you to maintain some control within your workgroup over documents that are being worked on. The art of keeping documents consistent is up to each person in your workgroup. If someone sees an opportunity for formatting changes in a document, consider that the change be incorporated into the master template and then imported throughout each document in the book (or not at all).

Note

For more information on format overrides, see Chapter 13.

One result of making slight changes here and there to page layouts, and paragraph and tables formats is format overrides. Format overrides mean that a change was made to a particular format that no longer matches the original predefined format. Here's how that works: Say that you have a predefined paragraph tag, Body. Now, for just one paragraph that is tagged with Body, you make a change to one of the Basic properties and apply that change to the currently selected paragraph using the Apply To button. You see an asterisk next to the paragraph tag name in the formatting bar. This asterisk means that the format of this particular paragraph no longer matches the predefined format in the Paragraph Catalog. In addition, a format override message window appears the next time you make changes to that paragraph tag using the Update All button.

To ensure consistency across document files, avoid incorporating formatting overrides into your documents whenever possible.

File Management

If you filed memos and other papers into a file cabinet, you wouldn't just put them into any file folder. Usually, memos or other papers are filed in some alphabetical, numerical, or other order that you determine ahead of time.

In the same way, file management is an important aspect while you work with FrameMaker. This section explores the benefits of organizing your files.

Organizing Your Files

Before you start a new documentation project, plan a file-organization method and then stick with it. The easiest and most logical way to organize your files is in a hierarchical fashion.

For example, say that you create a folder called Project A (see Figure 1.1). The Project A folder houses all the FrameMaker document files that make up a book and subfolders that contain graphic files used throughout each document.

Figure 1.1. Creating folders helps you organize your files.

Putting all the ingredients of a documentation project into a single folder enables you to later move these files to a different location, if necessary. Putting everything into a single folder also ensures that you don't break cross-references and links between document files, referenced graphics, and text insets.

With hierarchical file organization, if you want to move your files to another location, you can easily copy or move the folder that contains all the files. If you use other organizational methods, you have to move all the folders that contain some piece of the project in order to make it work properly in another place. You need to understand more about file location paths to carry out that plan.

File Location Paths

Numerous alternatives exist for how you ultimately decide to organize the ingredients of your FrameMaker projects. Understanding how FrameMaker stores file locations might help you during this phase of the project plan.

If you are importing referenced graphics or text insets, FrameMaker uses relative pathnames (folders and files that are relative to, or within, the current folder). As long as you keep these graphics and text insets in the same relative location, FrameMaker can still find the files if you later move them. If you import a file that is located in a folder which is above or outside of the current folder, however, FrameMaker uses an absolute pathname (an explicit list of folders starting at the highest in the hierarchy).

With absolute pathnames, keeping the files in the same relative location no longer works if you move the files. The path must be exactly the same, which is not possible if you move the files. With that, you have to deal with broken links between document files and referenced graphics or text insets, and cross-reference links between files and book file path locations.

File-Naming Conventions

Although FrameMaker files transfer easily from one hardware or software platform to another, file-naming conventions do not. It's always a safe bet to come up with a nomenclature that can withstand the limitations of any hardware or software platform.

For example, suppose that you created a book file that includes document files and referenced graphics in a computing environment configured for long file-naming.

Say that you move that book file and its included components to a computing environment that is set up for eight-character filenames. In this case, you can expect filenames to become truncated. As a result, the book file does not work properly because it can no longer find the original filenames. In addition, when the filenames change (are truncated), FrameMaker can no longer find cross-referenced files and referenced graphics.

A good, solid file-naming convention is a valuable part of your overall project plan. After you decide on a naming convention, set FrameMaker's Compatibility Preferences, as shown in Figure 1.2 (to get to Compatibility Preferences, go to File > Preferences).

Figure 1.2. You can name your file so it's cross-platform.

Adding Graphics from Another Application

When you create documents in FrameMaker, you often use graphics from other applications, such as Adobe Photoshop, Illustrator, or another graphic program. You have some considerations in deciding what graphic file types work best for your project and whether to import by reference or copy graphics into a document. This section explores those considerations.

File Types

Although FrameMaker supports many graphic file types, you might want to investigate which of these work well for your project. You might ask yourself the question, "How do I plan to work on documents and what will my end product be?" Then find the common denominator that works for all occasions.

For example, if you work in a multi-platform environment, creating and importing graphics that can only be viewed in one computing environment is not always the best solution. Importing graphics at a lower resolution for displaying onscreen is not a good solution if you also intent to print the document.

During the planning phase, experiment with various graphic file types and resolutions and take them through the import, viewing, and printing or PDF process to determine which type provides the best results. Again, if you find this out late in the production process, resaving and reimporting all those graphics will not be fun, especially when you could have avoided it.

Understanding Copied and Referenced Graphics

You have the option to import graphic files by reference or by copying them into a document. Do some experimenting before you begin the actual project to decide which method works best for you. If you decide to change the method later in the production process, and you already incorporated numerous graphics into your documents, you must reimport each graphic.

You choose to import a graphic by reference or to copy the graphic into a document by selecting a radio button in the Import File dialog box, as shown in Figure 1.3. Keep in mind that the radio button that you selected the last time you imported a file becomes the default the next time you import a file.

Figure 1.3. This dialog box allows you to either import or copy a graphic into your document.

Let's review each method's advantages and disadvantages.

Copied Graphics

When you copy graphics into your FrameMaker documents from another application, they become part of your document's file size. This method works well for documents that do not have many graphics (and the graphics are small in size).

What happens to a typical document file after a graphic is copied into it? Suppose that you have a FrameMaker document file that is 35KB and a JPEG image that is 515KB. Now import that image into the document file by copying it. Save the document. The document size now grows by leaps and bounds to 6,596KB! And that's just after copying one graphic into the document. Imagine if you were to import 10 graphics of the same size. Your document file would become too large to easily manage.

Another disadvantage to importing graphics by copying is that if you need to make any changes to the graphic, you must make the change in the source application and reimport the graphic into the FrameMaker document.

Referenced Graphics

When you import graphics by reference into FrameMaker documents from another application, it does not become part of your document's file size. The graphic appears to be part of your document, but it is really referencing a file that's being stored outside of the document.

Given the same scenario from the previous section, what happens when the graphic is imported by reference instead of being copied into the document? With a FrameMaker file that is 35KB and a JPEG image that is 515KB, the FrameMaker document does not grow in size after the graphic is imported. It remains at 35KB (that is, if you did nothing else to the document).

Importing graphics by reference keeps your document's file sizes down and, therefore, makes them easier to manage. Another great advantage is that, if you want to make changes to the graphic, you can make the changes directly to the source application; the next time you view that graphic in FrameMaker, the graphic automatically reflects those changes.

Note

For more information on generating a list of references, see page 261.

A disadvantage to referenced graphics does exist, however. You must pay close attention to the file management of graphics that are being referenced in documents with respect to file location and naming. This is because the graphics are stored outside of the Framemaker document. That's where a list of references can help you. A list of references for imported graphics helps you keep track of referenced graphics for all your documents.

Working with a Group of Coworkers

If you plan to work with more than one person on a project, consider a plan as to how you intend to work together. Take a look at two tasks that you might want to work into your overall plan.

Locking Files When Working over a Network

Note

On a Macintosh, only one person can use a file at one time.

If you work in a Windows environment over a network, understanding file locking reduces confusion for those working on individual files. Say that you stored all the ingredients of a FrameMaker project on a central file server, and each document is to be worked on directly from that file server.

In this case, if more than one person works on a particular document, another person can open the same document, even though it's already in use, and make changes at the same time. This is where understanding how file locking works is important to the success of your project.

Back to Basics

To turn on file locking, select File > Preferences, and click Network File Locking.

You might have seen a file located in the same folder as your original file, named filename.fm.lck. If you have Networking File Locking turned on (see Figure 1.4), this file is automatically created each time you open a FrameMaker document, and it's erased when you close that same file.

Figure 1.4. The Network File Locking preferences.

If someone on the network has a particular file open and a second person opens that file, a dialog box appears. This dialog box provides information about the file, such as the document name, the name of who opened it, the date and time it was opened, and the computer on the network that opened it.

The second person has three choices after opening the file that is already in use:

• Open for Viewing Only. View the file and not make changes

• Open Copy for Editing. Create a copy of the file for editing

• Reset File Lock and Open. Edit the file and reset the file locking

The Network File Locking feature really acts as a warning mechanism for multiple users of the same file over a network. You can always turn off this feature. Regardless of which you choose, decide beforehand how your workgroup should access document files.

Creating a Template Style Guide

Another useful item to have on-hand when you work with a group on document files is a template style guide. Then everyone working on the documents will know what paragraph tag names are used for particular elements in the documents, what table formats to use and when, and understand cross-reference formats or rules about character formatting.

Note

For more information on creating a template style guide, see Chapter 13, "Typical FrameMaker Headaches."

A template guide does not have to be elaborate. You can put together a simple two- to four-page document with each paragraph tag listed with an explanation of what it's used for. If you tag each explanation with the paragraph tag that is being defined, the user of the template has a better idea of what it looks like.

Include all facets of the template in a template style guide. This ensures consistent use of the template across documents.

Summary

Mapping out strategies for your FrameMaker projects is an involved process, but it's an important phase in the document plan that should not be overlooked. Having a plan in place before you start a project helps keep files organized, prevents file path connection failures, ensures the use of a file-naming scheme that works on any platform, and enables others who work on your project to create consistent results.

In this chapter, you discovered the importance of having a plan before integrating more advanced features into your documents. After you find a plan that works, stick with it and use it as a model for future FrameMaker projects.

CONTENTS