what’s the “value add”? - stc rmc · published with framemaker 4 won the “best of show”...

Production Guides

What’s the “value add”?

Kathryn L. RamseySr. Technical Writer,

Quantum Corp.

June 17, 2004© Copyright 2004 by Kathryn L.

Ramsey2

Who is Kathy Ramsey?

Senior member of the Rocky Mountain Chapter of the STC; also on the Council.1993: A hardcopy manual I worked on and published with FrameMaker 4 won the “Best of Show” award (in the Technical Publications Competition).Co-manager of the Online Competition and the Online SIG (9 years).19 years industry experience.


Ramsey3

What is a Production Guide?

Not the same as a Style Guide or a Writer’s Handbook.Essential to have if you are redirecting information into different forms.This publication focuses on the mechanics of getting the work done.Is more than just a series of procedures, however.Provides some important conceptual information; some background information; some summary information.


Ramsey4


Ramsey5

Benefits of automating (and documenting) your processes

Simplicity– Less confusion, less dependency on memory.

Consistency– Automated processes encourage consistency.

Professionalism– Writers work “transparently”; prevents writers from

implementing tricks that only one person understands.

Faster throughput– Computers excel at repetitive, methodical tasks.


Ramsey6

Who to include?

All the tech writers.Production specialist, if you have one.Tools person, if you have one.1-2 levels of management, so you have their support and “buy-in”.Your change-management personnel (they may have valuable or innovative ideas).


Ramsey7

What to include?

The mechanics of your process.Housekeeping issues.Methods of publishing.Miscellaneous general pointers.Special processes used.Font tips, techniques, and gotchas!


Ramsey8

The mechanics of your process

Original Documents

CD-ROM

Print

Web (HTML)


Ramsey9

Housekeeping issues

GraphicsTemplatesIndexing guidelinesStaying consistentWhere to store your filesAdding metadata to your filesBackupsArchiving


Ramsey10

Production issues that have to do with graphics

Specify file format to use, colors or no colors, dpi at which to capture and save, where to store, use of borders or frames, use of shading, etc.


Ramsey11

Methods of publishing

PDFHTMLXMLOnline helpCD-ROMWeb sitePaper


Ramsey12

Miscellaneous general pointers

Topic attributes (when working on an online help project)Where files are stored (special servers)Graphics settingsDistilling options (which ones to use)Troubleshooting tips


Ramsey13

Special processes used

Scripts or macros that are used to expedite the publishing process.Spreadsheets that are used to keep track of metadata or to assist with book-building.Job aids that must be used.Checklists that must be completed.


Ramsey14

Sample scripts, listed

Very similar to FilesforSolar.fsl, but is used instead for print production. In addition to removing things, this script applies new master pages in many places, and imports the styles that “work” for printing.

FilesforLunar.fsl

Works through a book, calling various subroutines that perform different functions, most notably removing extraneous things.

FilesforSolar.fsl

Works through a book; performs a “Save As” of every file to a matching subdirectory in a different location that you specify in the script.

BookSaveAs.fsl


Ramsey15

Sample spreadsheets —where did I get them?

I borrowed the following sample spreadsheets from Rob Hanna, a Senior Technical Writer that I met through STC’s Single Sourcing listserv.Rob is a big fan of automated publishing and single sourcing.Rob works for International Financial Data Services Ltd., in Toronto, Canada.


Ramsey16

Sample spreadsheet #1

Document outline worksheetThis data is assembled from other worksheets using metadata captured for each individual enhancement.Each enhancement is authored as an individualFrameMaker document (recorded in column D) that is brought into the document by reference.The records are sorted by columns B and C.The Outline String (column F) is copied into a blank template for each chapter file (indicated in column A).


Ramsey17

Sample spreadsheet #1, cont.

Using Search and Replace, Rob quickly formats the document and copies in the documents by reference at each indicated placeholder.The formula in column F builds the text string that is pasted into FrameMaker.Regrettably, much of the logic that assembles this worksheet is disabled to create this standalone example.


Ramsey18

Sample spreadsheet #1, cont.


Ramsey19


HTMLHelp TOC BuilderRob’s help project contains 3000 topics. All metadata, including title and unique identifier (PUID), are stored in databases that Rob assembles here for publication.

Rob recreates the TOC structure and builds the HTML needed to create the .HHC file. He copies the text in column K to a text editor and saves as “TOC.hhc”.

He opens it in HTML Workshop to see the graphical representation.


Ramsey20



Ramsey21

Sample job aid (typing special spaces and hyphens)


Ramsey22

Sample checklist (for translations)


Ramsey23

Font tips, techniques, and gotchas!

Different types of fontsFont substitutionSpecial characters (importance of checking)Asian or Arabic fontsThe impact on book-building (within Frame) if files won’t open due to missing fonts


Ramsey24

Fonts, continued


Ramsey25

Different types of fonts

TrueType fontsPostScript fontsOpenType fontsUnicode

Note: Different publishing environments and the various print vendors have different expectations vis-à-vis fonts used.


Ramsey26

Different types of fonts, continued


Ramsey27

Font substitution

Windows PCs ship with a predefined list of fonts; when your project uses additional fonts (usually to achieve special effects), you may see messages like the one above about “Unavailable Fonts.” This is especially likely when multiple authors are sharing the same set of files.


Ramsey28

Special characters

Degree symbols correct (as expected)

Degree symbols incorrect (not as expected)


Ramsey29

Asian, Arabic, or Hebrew fonts

Present special challenges.Documents containing Asian text can usually be displayed on-screen, even while most Asian language features are disabled.To get the full set of Asian language features, you have to run in a version of Windows that is able to display Asian text in windows, menus, and dialog boxes.Arabic and Hebrew proceed from right to left, which is another challenge for desktop publishers.


Ramsey30

Unicode

Unicode fonts can contain large character sets of up to 65,000-plus characters, including all Western characters and accents as well as non-Western (for example, Japanese or Chinese) characters.For more information about Unicode, refer to the following web site:

http://www.unicode.org


Ramsey31

The impact of fonts on book-building

FrameMaker always displays alerts about missing fonts; these alerts require a human response.Human response is slow compared to how fast computers can work.Get the various “bugs” worked out in advance, so that the process is not hampered by error messages and alerts.


Ramsey32

Benefits of documenting your production processes

Documenting your production processes forces you to think clearly about what you are doing.Structured and/or automated authoring looks forbidding to others, especially when it appears to neglect the fine points of the technical writing craft.Writers are reluctant to change comfortable, time-tested practices; nevertheless, they will appreciate a thorough, clearly-written set of procedures.Provides a way to communicate with others, even if lots of additional coaching and training is needed.Helps the writers (and others outside the department) understand the TechPubs department’s workflow.


Ramsey33

Questions?Ask now or e-mail later to:

[email protected]

No spam, please!!!