Re: Another newbie question: Advice sought on how to structure my project

["Thomas Michanek" <thomas.michanek@xxxxxxxxx>]

*** The original message appeared on the FrameUsers mailing list.
*** This reply is sent only to the framers@omsys.com mailing list.
*** If this message is useful, consider copying it to FrameUsers.

From: "Daniel Spreadbury" <dspreadbury@sibelius.com>
> The User Guide I'm working on is structured as follows:
> -- the imprint (1 page)
> -- the table of contents (2 pages)
> -- 'Start here' section (c. 10 short chapters, c. 20 pages)
> -- 'Quick tour' section (c. 20 short chapters, c. 60 pages)
> -- 'How to' section (c. 12 short chapters, c. 30 pages)
> -- 'Reference' section (c. 80 chapters, c. 350 pages)
> -- 'Glossary' section (single alphabetical list, c. 20 pages)
> -- 'Index' section (c. 20 pages)
> -- 'License agreement' section (3 pages)
> 
> None of the chapters are more than 12 pages, and most are quite a bit 
> shorter than that.  Chapters can start on either a left or right-hand 
> page, but the bigger sections all start on right-handers.
> 
> Should I use separate .fm files for every single chapter, or just for 
> each section?

What really decides this is not so much the page count, but the numbering.
Page numbering cannot restart in the middle of a FM file, so if you're
using "chapter - page" or "section - page" numbering you need to start a
new file whenever the page number restarts at 1. If you're using continuous
page numbering throughout the manual, which is what I would recommend, then
you can have the file breaks anywhere.

Also, a new file always means a new page break in FM. That is, if your
chapters can start half way down a page, then you cannot make file breaks
at that level. If your chapters always start on a new page, no problems.

Since you have over 100 small chapters, I would definitely not put each
chapter in a separate file. Even though a book file can manage any number
of files, it becomes hard to find and scroll among hundreds of files.
For the smaller sections, put each section in a single file.
The "Reference" section, however, is so large that I would consider breaking
it up, not into 80 files, but perhaps 5-10 files. FM can handle a 350-page
file without any problems, but it would be easier for you as a writer with
a smaller file (opening/saving it, paging through it, finding info, etc).
Can the reference chapters perhaps be grouped into logical parts? If so,
those "parts" would be a good candidate for file breaks.

You didn't mention whether the sections or chapters are numbered, but any
numbering scheme can be handled by FM. In the book file setup, you can
control how numbering of pages, sections and chapters are handled on a
file-by-file basis (if they would restart from 1 or continue on from the
previous file).

In my experience, a good "break-up" of a manual a few hundred pages long
results in a book file with 10-30 files, each file having 10-50 pages.
Of course, you shouldn't "merge" or "split" chapters just to follow these
guideline numbers, but it's a rule of thumb.

One more thing: make sure to keep graphics a separate files, imported by
reference. Store the graphic files in one or more subfolders to the
book file folder. The FM files go directly in the book file folder, i.e.
avoid subfolders for the FM files (for a manual of this size, at least).


- - - - - - - - - - - - - - - - - - - - - -
Thomas Michanek, FrameMaker/UNIX/MIF expert
mailto:Thomas.Michanek@telia.com   (Sweden)
http://go.to/framers/
- - - - - - - - - - - - - - - - - - - - - -
Join the low-volume "Free Framers" mailing list: send an email
to majordomo@omsys.com with "subscribe framers" in the body


** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **