User manual | NETGEAR router, gateway, wireless adapter Production Guide
Add to My manuals191 Pages
advertisement
350 East Plumeria Drive
San Jose, CA 95134
USA
February 2012
Part Number TBD v1.0
Production Guide
Technical Publications
Production Guide
© 2010 NETGEAR, Inc. All rights reserved.
No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language in any form or by any means without the written permission of NETGEAR, Inc.
Trademarks
NETGEAR, the NETGEAR logo, and Connect with Innovation are trademarks and/or registered trademarks of
NETGEAR, Inc. and/or its subsidiaries in the United States and/or other countries. Information is subject to change without notice. Other brand and product names are registered trademarks or trademarks of their respective holders. © 2011 NETGEAR, Inc. All rights reserved.
Statement of Conditions
To improve internal design, operational function, and/or reliability, NETGEAR reserves the right to make changes to the products described in this document without notice. NETGEAR does not assume any liability that may occur due to the use or application of the product(s) or circuit layout(s) described herein.
2
Contents
Chapter 1 The Landscape
Editor (Contract or Permanent) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Cross-Functional Teamwork. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 2 Document Sets
Home and Business Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Home Product SBPU Group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Model Numbers and Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Chapter 3 Start a Project
Localized and Goes in Box. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Estimate Doc Creation Time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3
Production Guide
Chapter 4 Document Preparation
Part Numbers and Bar Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Requesting Part Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Part Number Anatomy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
When a Document Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Document Bar Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Add a Bar Code Directly to the PDF. . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Quick Response (QR) Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Printer Contact Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Export Graphics from .ai Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Save to an Older Version of Illustrator . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Import Screen Captures into FrameMaker . . . . . . . . . . . . . . . . . . . . . . . 46
Use a Dedicated Laptop for Screen Captures . . . . . . . . . . . . . . . . . . . . 46
Combine Screen Captures with Photoshop . . . . . . . . . . . . . . . . . . . . . . 47
Use WinTV to Get Screen Shots from a TV Display . . . . . . . . . . . . . . . 48
Update Screen Shots When Product Name Changed . . . . . . . . . . . . . . 49
Stop the Font Substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Set Up a FrameMaker Book without Blank Pages . . . . . . . . . . . . . . . . . 52
Make a PDF of Parent and Child Books. . . . . . . . . . . . . . . . . . . . . . . . . 53
Disconnected Pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Links to Internet Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Turn Off Annoying Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Import Text Files into FrameMaker. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4
Production Guide
Spelling, Grammar, and Style Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
FrameMaker to Word through PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Readability Check Caveats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Chapter 5 Document Reviews
Fast Track Review Schedule for Wireless Adapters . . . . . . . . . . . . . . . . . 64
Comment Acceptance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Document Approval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Chapter 6 Finalize Documents
Content (Routers/DG Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Preset Security (Router/DG Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Preset Security Manuals (Router/DG Only) . . . . . . . . . . . . . . . . . . . . . . 70
Compliance, GNU License, WEEE Notice, Warnings . . . . . . . . . . . . . . 70
Prepare and Name Files for Agile Release . . . . . . . . . . . . . . . . . . . . . . 71
Sample File Names for QIGs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Sample File Names for Manuals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Sample File Names for Booklets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Final Hand-Off from Offsite Writers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Completed Projects That Do Not Go into Agile . . . . . . . . . . . . . . . . . . . . . 77
5
Production Guide
Notification - All products Except Storage . . . . . . . . . . . . . . . . . . . . . . . 78
Notification - Storage Products. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Chapter 7 PDF Procedures
Optimize PDFs for Search Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Set Metadata within Frame. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Add Metadata to the PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Other Search Engine Optimization Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
PDFs for Online Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
PDFs for Quick Install Guides (QIGs). . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Prepare for Color or BW Printing (Preflight) . . . . . . . . . . . . . . . . . . . . . . . . 87
Link from within a PDF to External PDFs . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Section 508 of the Americans with Disabilities Act. . . . . . . . . . . . . . . . . 93
Generate a Tagged PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Test a Tagged PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Send PDFs Out for Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Make Large PDFs Available for Review . . . . . . . . . . . . . . . . . . . . . . . . . 99
Chapter 8 Custom Tools Reference
NetgearTools Folder and Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Commands and Book Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
List of Cross-Ref Formats in Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Edit Cross-Ref Formats in Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Collect Outside Cross-References . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
List of Graphics in Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Move Unused Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Collect Outside Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
List of Variable Definitions in Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
6
Production Guide
Edit Variable Definitions in Book. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Set PDF Metadata for Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Creating Useful Metadata (Optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Background Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Apply Character Tag to URL Markers. . . . . . . . . . . . . . . . . . . . . . . . . . 118
Template Conversion Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Import Formats from Latest Templates into Current Book . . . . . . . . . . 120
Convert Figures/Notices Tables to Paragraphs . . . . . . . . . . . . . . . . . . 120
Remap Old Tags to New Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Fix Cross-Reference Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Add/Setup GenFiles, Numbering and Update Book . . . . . . . . . . . . . . . 123
Chapter 9 Old Style to New Conversion Tutorial
Work on the Book Files Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Finalize the Book File Set in FrameMaker . . . . . . . . . . . . . . . . . . . . . . . . 127
Update the Book Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Run the Conversion Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Update to Newest Version of Template . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Appendix A Install Custom Tools
Appendix B Templates Reference for Manuals
FullManaulTOC.fm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Chapter Template.fm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Appendix Template.fm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
7
Production Guide
FullManaulTOC.fm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Chapter Template.fm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Appendix Template.fm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Appendix C Office and Laptop Tips
Desktop Sharing for a Meeting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Remote Access to the V Drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Make an Email Distribution List in Outlook. . . . . . . . . . . . . . . . . . . . . . . . 163
Extract Files from an Apple Archive (sit) File . . . . . . . . . . . . . . . . . . . . . . 164
Appendix D DITA Reference
Reference a Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Conditional Processing Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
DITA Map Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Bookmap Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Index
8
1.
The Landscape
Departmental roles and other teams
1
The production guide covers technical publications procedures for creating product documentation in North American English. This guide includes information on people and teams, document sets, document reviews, how a project starts and finishes, and production guidelines for producing deliverables.
Some departmental information regarding desktop sharing and maintaining your NETGEAR
Appendix C, Office and Laptop Tips
. The guide finishes up with a section on the CD Build process in
Appendix D, CD Build Process
. The goal of this guide is to be a complete reference for technical publications procedures.
This chapter covers the following topics:
•
•
•
9
Production Guide
What We Do
Technical publications handles the following documentation-related tasks:
•
Writes and updates documentation
•
Creates departmental templates and designs
•
Lays out graphics and creates illustrations
•
Edits customer-facing materials such as GUI text and help files
•
Manages document scheduling and production for product releases across all BU’s
•
Builds the CD with all the product-specific information and deliverables that are needed
Job Roles
Technical publications has the following job roles.
Lead Writer
The lead writer not only writes product documentation, but also represents the technical publications department to one or more business units in a leadership capacity. This position is usually an employee position, but a contractor can assume this role also. Permission from
HR and the second-level manager are needed for the contractor to get access to the internal drives.
The lead writer also does the following:
•
Represents technical publications in cross-functional team meetings.
•
Is on the email list for cross-functional team communications to monitor project changes and answer questions.
•
Receives writing assignments from the business unit.
•
Requests documentation part numbers from document control.
•
Does the writing assignments or asks a writer or contract writer to do them.
•
Establishes the review team and initial schedule.
•
Notifies the writer of schedule changes as applicable.
•
Creates the product page on docs.netgear.com and posts files: http
://docs.netgear.com/modelnumber/enu/partnumber/.
•
Receives the final files from the writer.
•
Posts the final files to V:\Current Projects and V:\Operations\Document
Control\AgileDropFolder\.
•
Notifies the Agile analyst that documents are ready for pickup via TrackIt: http://trackit.netgear.com/TIWEB8/scripts/TIWebPortal/TrackItUser.asp
•
Notifies the Agile analyst, localization, product engineer, Web engineer, and technical publications manager by email that files are ready for Agile pickup.
The Landscape
10
Production Guide
Writer
An employee writer writes product documentation. He or she might be assigned to a specific business unit or work across two or more business units. Duties are the same as those of a contract writer with the addition of the following:
•
Attends cross-functional team meetings as needed or as time permits.
•
Is on the email list for cross-functional team communications to monitor project changes and answer questions.
•
Receives writing assignments from the lead writer.
•
Either hands off the final files to the lead writer for backup to AgileDropFolder and Current
Projects, or puts the files there and notifies the lead writer when they are there.
•
Upon agreement by the lead writer, might notify the Agile analyst, localization, product engineer, web engineer, technical publications manager, and lead writer that the files are ready for Agile pickup by email.
•
Upon agreement by the lead writer, might post files to docs.netgear.com.
Contract Writer
A contract writer writes product documentation. He or she might be assigned to one business unit or work across two or more business units.
•
Receives writing assignments from the lead writer.
•
Determines where illustrations are needed, contacts the illustrator, and if needed, recommends a meeting with the engineer or product line manager, plus the writer and illustrator.
•
Handles desktop publishing/formatting based on guidelines from the production person and/or designer.
•
Manages review cycles and incorporates review comments.
•
Works directly with the review team to develop, review, and finalize document.
•
Notifies the lead writer of schedule changes as applicable.
•
Notifies the lead writer when the doc set for a product is complete.
•
Hands off the final files to the lead writer for back up to AgileDropFolder, Current Projects, and posting to docs.netgear.com.
The Landscape
11
Production Guide
Editor (Contract or Permanent)
The editor reviews all documents before they are released for editorial style, grammar, punctuation, and other things as specified in the Editorial Style Guide.
•
Uses the editor’s checklist on the inside front cover of the Editorial Style Guide to enforce editorial styles.
•
Works with writers to establish the style guidelines and rules.
•
Submits word lists with preferred spelling and usage for inclusion in the Editorial Style
Guide.
Designer
The designer is responsible for the look and feel of the printed and online documentation.
•
Uses the branding guidelines produced by marketing to establish colors and fonts used in documentation design and illustrations.
•
Determines page layouts for a consistent look across the various document types while customizing the layout for the best presentation of each document’s unique content.
•
Works with illustrators to determine art guidelines such as colors, fonts, line widths, color format (RGB or CMYK), and develops an art catalog as needed.
•
Implements or works with the production person to implement templates.
Illustrator
The illustrator creates illustrations and other art for all the docs, adhering to the art guidelines set forth by the designer in collaboration with the illustrator.
•
Uses Adobe Illustrator and Photoshop.
•
Takes photos of units to make front cover drawings.
•
Does line drawings as needed.
•
Does cabling diagrams for place mats as needed.
Production Person
The production person is an expert in FrameMaker who backs up the team as follows:
•
Puts text into an existing or customized template.
•
Updates documents with product name changes.
•
Implements and/or designs templates.
•
Creates documents as needed under the direction of a lead writer.
The Landscape
12
Production Guide
Manager
The manager is responsible for a team of employee and consultant technical writers, designers, illustrators, and production personnel who produce all printed and online product documentation in U.S. English, except product online help. The CD build release engineer also reports to the manager. See
Appendix D, CD Build Process
for more information. The manager has the following responsibilities:
•
Sets employee goals, hires, trains, and develops a strong, collaborative team.
•
Ensures the team provides all required printed and online deliverables on schedule.
•
Is responsible for documentation quality and quality improvements.
•
Studies the competition documentation to make sure NETGEAR documentation is at least on par.
•
Establishes efficient processes to streamline the work.
•
Collaborates across all business units and functional teams.
•
Manages and works with geographically-dispersed teams.
•
Runs the weekly technical publications departmental meeting.
•
Owns the Production Guide and the Editorial Style Guide.
Cross-Functional Teamwork
Technical publications is within the Engineering Services organization because it is a shared service. The department provides printed and online documentation for the following
NETGEAR business units: Home, Small-Medium Business, Service Provider, and Storage.
This section describes how the technical publications department interacts with other teams.
Marketing
The marketing team is a separate organization with product line managers (PLM’s) dedicated to the various business units. The PLM for a business unit develops new product ideas, researches these ideas, and performs a competitive analysis to see if they are worthwhile for
NETGEAR to pursue. The PLM is also responsible for determining the formal product name and the short name to be used in the documentation, on the packaging, and in marketing documents.
The PLM presents new product ideas to upper management for approval at Product Change
Management (PCM) meetings. Approved products advance through the PCM checkpoints as they reach major milestones.
Technical publications creates installation guides at the request of marketing. Marketing has the final say on costs, paper, color or not color printing, and the PLM should be included in installation guide reviews.
The Landscape
13
Production Guide
Engineering
The engineering teams are within the business units and coordinate new product releases, maintenance releases, and certification processes for gaining new business. Individual engineers are assigned to products and are called product engineers (PEs). When documentation is needed for a product, the product engineer approaches technical publications and works with the assigned writer to complete the needed documents. The PE reviews all documents.
Tech Support
The technical support team is a separate organization with support engineers dedicated to the various business units. Include the technical support person for your business unit in reviews for all documents.
Product Design
The product design team is part of Engineering Services. They are responsible for compliance, labels, and unit photos. Technical publications puts compliance information in user/reference manuals as described in
with product design to get the label that goes on the bottom of the unit. Technical publications puts the label in the setup manual or install guide as needed.
Product photos are available in V:\Marketing\Product Files\ModelNumber in the Product
Images or GUI Banners directory. However, technical publications typically has an illustrator take unit photos that are turned into the front page cover and front and back panel art for the manuals. Sometimes you might need to update the product name in an illustration. Look in the GUI Banners directory, and if you find what you need, you can cut and paste the name onto your artwork.
Mediabin is another repository for art and other media-related items. Access it here with your
LDAP user name and password:
https://mediabin.netgear.com
. Look under Corporate Assets for logos, product art, videos, and more.
Usability
A small usability engineering team is within the Home business unit. Technical publications works with the usability team on user interface design, terminology, color schemes, usability study results, and more for product improvement and to inform new directions in documentation.
Localization
The localization team is based in Taiwan and handles document translation. When the lead writer archives a document set in Agile, he or she also notifies the localization team so they can pick up the docs for translation. Sometimes we work with the localization team on
The Landscape
14
Production Guide
requests for smaller printed documents to fit inside smaller boxes or to figure out ways to save printing and translation costs.
Packaging
The packaging team coordinates the design and creation of our product packaging. They can provide NETGEAR and competitor box samples. Sometimes we ask to see the NETGEAR packaging for a particular product when we are designing a smaller printed document to go inside. This can help us determine whether or not the document will fit inside the box as intended.
Legal
The legal team advises us on copyright and trademarking questions and provides the applicable text as needed.
The Landscape
15
2.
Document Sets
Documents vary across business units
2
Technical publications delivers documentation sets appropriate for the business unit and geared to the product line. This means there are many different types of documents, and even the same type of document as it is used across product lines can have different information or additional sections. This chapter provides a high-level explanation of the document types as they pertain to the business units. Localization is also covered.
The following topics are covered in this chapter:
•
•
•
•
•
•
16
Production Guide
Document Types
The most common documents are:
•
Quick install guide (QIG) or place mat: A product can have either a QIG or a place mat.
A place mat is used for routers and gateway products and shows detailed package and cabling information on the first page.
QIGs are two-sided print documents that fold and ship in the package with the product. If there is a CD, a PDF of the document also goes onto the CD. These documents cover the basics of how to connect the product and get it working.
•
Setup manual: The setup manual echoes the CD wizard installation instructions for products that have a CD wizard. It is for customers who cannot use the wizard either because their computer does not have a CD drive or they use an operating system such as Linux that the wizard does not support. A PDF of the Setup Manual goes onto the CD.
Note:
Setup manuals are being phased out on routers and gateway products that are configured with preset security.
•
User manual: Documents the product GUI. If the product has a simple and a complex installation flow, the more complex method goes into the User Manual so that the QIG is not too crowded. The User Manual also provides background technical information for product features to assist sophisticated users who want to customize their installation.
•
Hardware installation guide (HIG) for managed switches: This shows how to install the switch hardware and also covers compatible optional adapters and modules.
•
Software administration manual for managed switches: This is a lengthy task-based book. It covers examples of how to complete tasks with either the GUI or by CLI commands.
•
CLI manual for managed switches: Documents CLI commands for the switch.
Document Sets
17
Production Guide
The document set varies depending on the product and whether there is a CD.
Product CD
Accessory, antenna, or simple switch
No
Application
Smart & managed switches
No
Yes
Documentation
Quick Install Guide (QIG)
Digital media players (EVA) Yes
Powerline
ReadyNAS
Router/gateway/modem router
No
Yes
Yes
Yes
No
Wireless adapters or range extenders
Yes
User Manual (UM)
QIG
Hardware Installation Guide (HIG)
Software Guide (installation, setup, etc.)
Software Administration Guide
CLI Manual
QIG
User Manual
QIG
QIG
UM
QIG
Software User Manual
Hardware User Manual
Place mat
Setup Manual
User Manual
QIG
User Manual
QIG
User/Reference Manual
Document Sets
18
Production Guide
Home and Business Products
NETGEAR products can be divided into two broad groups consisting of home products and business products.
•
Home retail products. These can be either home consumer products sold directly to consumers or service provider products sold to carriers for their customers to use in a home environment. Some examples are wireless routers, gateways, modem routers, wireless adapters, digital media players, and Powerline products. Retail customers range from first-time users to experienced users. Carrier group technicians are technically knowledgeable.
•
Business products. The small to medium business and network storage business (NSB) units make products for use in a business environment. Wireless routers, managed switches, and fire walls are examples. Users in this group are technically knowledgable.
Home Product SBPU Group
This group has several types of products. It is important to know which kind of product your document is for.
Platform Products
These are developed as demonstration models. Typically, engineering needs only a rough draft of the user manual for certification. The user manual should show the right hardware and include the right feature set, but the GUI does not have to be documented precisely because it might change. Sometimes they also need a QIG. Often, these documents do not have part numbers, and their schedules are different from those for other NETGEAR products. Files are delivered into 4Backup on the FTP site. Sometimes, months later the demo model becomes an actual product. Then these files can be used as a base for the documentation.
Carrier Products
These products are sold through carriers such as Comcast or Times Warner. They do not sell retail with a gift box. There might or might not be an IG, depending on how the carrier handles installation. There is a user manual, which might be customized and used only by the engineering group of the carrier. Sometimes they have special security needs. For example, there was a gateway that a post office group bought in which each modem router had a unique security key based on its MAC address. Many have a super user login in addition to the regular admin login.
Retail Products
These docs are fairly typical for home products and are customer facing as opposed to written for engineers.
Document Sets
19
Production Guide
Product Names
Marketing develops product names, which appear on the gift box, in marketing collateral, and in the documentation. The gift box is the product package that is sold to the customer, and is usually created before the product documentation. Product name consistency across these media is very important, and for this reason it is up to the writer to find out the marketing-approved product long name and short name to use in the documentation.
Marketing sometimes changes the product names, so technical publications uses
FrameMaker variables for these names. The variables are easily edited and managed with
the Edit Variable Definitions in Book command, described in
An example of a marketing-approved product long name is N150 Wireless ADSL2+ Modem
Router. It’s marketing-approved short name is N150 Modem Router. The long name is typically used in the book title, compliance appendix, and in the first paragraph of the first chapter in the book. The short name or a generic name such as wireless modem router is used everywhere else.
Model Numbers and Versions
Model numbers and versions vary not only from product to product, but also from product line to product line with some inconsistencies across product lines. For example, business products do not have a space between the model number and version, but home products do:
Business product example: FVS318v3
Home products example: C814WG v3
Note:
Home products originally had no space before the version, but it was added later:
Document Sets
20
Production Guide
Localized Documents
The English versions of NETGEAR product documentation are used for all English-speaking countries such as North America, Australia, and the United Kingdom. Localized documents are made from the English versions, but have their own unique part numbers. Marketing decides whether the documentation for a given product is localized and into which languages.
For localized products, installation guides are always translated. Sometimes the setup and user manuals are also translated. Whether a document is translated or not affects it’s due date. Adequate time for translation has to be built into the docs delivery schedule so the installation guide is ready to go into the box and the setup manual is ready to be put onto the
CD that then goes into the box. See
Sometimes the localization team, which is based in Taiwan, requests that technical publications make the descriptions for common features consistent across sets to save on localization costs. We try to do this as much as possible without sacrificing quality and user experience.
Document Sets
21
3.
Start a Project
Organized projects are easier to track
3
Documentation projects start near the beginning of the product life cycle when the lead writer or manager is notified. The project could be a new project needing documentation or a maintenance release that requires documentation updates. The business units have slightly different methods for requesting and tracking project deliverables including documentation, but technical publications processes for starting a project are similar for projects from any business unit.
This following topics are covered in this chapter:
•
•
•
•
•
•
•
•
•
22
Production Guide
Project Kickoff
The project engineer requests product documents from technical publications.
•
The project engineer, the product line manager, and the technical publications
department work together to determine the documentation set. See
on page 17 for a descriptions and a table of the standard doc sets by product.
•
The project engineer recommends a similar doc set on which to base the new set. If the project is new without any similar doc set, you have the following options:
-
Find out if the product has a standard wizard or genie on a CD and get a list of features. Sometimes presentations are available with this information.
-
Get a unit as soon as possible so you can check the user interface for features.
-
Ask for a document that describes the LED behaviors.
-
Base the new set on multiple doc sets so you can pull the features you need from them.
-
Meet with the engineer and include the illustrator. Have the engineer demo the unit so you and the illustrator can ask questions.
•
The project engineer informs technical publications if there will be a CD and which version of the installation wizard or genie the product uses.
•
The project engineer provides a unit for screen captures, photos, and illustrations, or enables remote access if the unit has to be used in the lab.
•
The project engineer tells the writer whether the product is Class A or Class B for compliance purposes. See
on page 30 for more information.
•
The project engineer provides xfactory and other due dates. Typically there is a 50 percent and a 90 percent xfactory date. Technical publications uses the 50 percent date for calculating documentation due dates. Certification documents do not use xfactory
on page 24 for more information.
•
The lead writer calculates documentation due dates using the algorithms described in
•
The product line manager approves long and short product names to use in the manuals, in the product packaging, and in the marketing materials.
•
Product line manager determines which documents are localized. Localization is taken into account when the document due dates are calculated. See
on page 24 for more information.
•
The lead writer requests part numbers for the docs.
Start a Project
23
Production Guide
Calculate Doc Due Dates
Documentation due dates are calculated with the 50 percent xfactory date.
CD
Does the product ship with a CD?
Yes. Subtract 5 weeks from the 50 percent xfactory date to calculate the doc deliverable date.
No. Use the published 50 percent xfactory date to figure out the doc deliverable dates.
Localized and Goes in Box
Is the document localized? Usually install guides and setup manuals are localized.
Yes. Due date is xfactory – 7weeks
No. Due date is xfactory – 5 weeks
UM/RM for Web-Based Delivery
Due date is xfactory +2 weeks.
Estimate Doc Creation Time
Use these (very) generous guidelines to estimate how long it might take to create a document. You might need to calculate this when bringing in a contractor to help on a specific project.
Writing new content: 2 hours per page.
Editing: 30 minutes per page.
Incorporating reviewer comments: 30 minutes per page.
Certification Documents
The project engineer might need an installation guide or user manual for product certification.
In most cases, product content is not so important, but content relevant to the certification is very important. Not all products that go for and pass certification turn into real projects so the goal is to minimize the time and effort invested in creating certification docs.
There are generally two types of certification docs, simple and more involved. In both cases technical publications gets a documentation set from a similar project. Depending on how different the device to be certified is from the device described in the base doc set, follow either the simple or more involved process:
Start a Project
24
Production Guide

Create a simple certification document:

1.
Place a note on the cover saying the document is for certification purposes only and the screen captures and illustrations might not exactly match the unit.
2.
Place a note near the unit photos saying the document is for certification purposes only and the actual unit might not exactly match the picture.
3.
Change the product name everywhere.
4.
Remove sections that do not apply.
5.
Add short sections that are important for certification.
6.
Change the part number to Part#TBD to avoid confusion caused by leaving in the existing part number from the similar doc.
7.
Do not change screen captures and illustrations, except in a case where an initial screen is so different from the base doc set that it would be very confusing not to. Changing out the screens and illustrations is a lot of work and costs money, and the product might not get the go-ahead.
Create a more involved certification document:
1.
Do all of the above plus the following:
2.
Go through the GUI and put in screen shots for changing features and adjust the content accordingly.
Sometimes content is pulled from different books and combined to get the feature set needed.
3.
In particular, check and update the following as needed:
a. Does the product include automatic firmware updates or not,.
b. Are there variations on superuser, MSO, admin access, guest networks, multiple
SSID capability, WDS vs. no WDS.
c. Does WDS reside on the same screen as advanced WPS settings.
d. Check the Firewall rules, Block Sites, and Services screens.
e. Look for miscellaneous variations in LED behavior.
4.
Sometimes there are requests from the engineers for changes in the compliance content that need to be run by the NETGEAR compliance engineer.
Beta Documents
The project engineer might need only a partial document set for Beta. This could be a completed installation guide only or include a partially completed user manual. Beta documents typically have a note on the cover to indicate that these are Beta documents.
Documents in Agile
Agile is the database where items associated with a project are stored when the project releases. The items include the bill of materials (BOM), product label, CD label, engineering
Start a Project
25
Production Guide
documents, engineering change orders (ECOs), product documentation for all required languages, and more.
Sometimes lead writers need to locate documents in Agile to verify something or to get a copy to use as the basis for a new document set. If you know the part number for a document, you can put it into the search engine, and the document comes up.
Figure 1. Search on part number
However, if you want to see a list of documents and other items, you can search on the product model number with a wild-card and select Items like this:
Figure 2. Search on model number
Scroll down to find the documents, which will be listed like this:
Figure 3. List of items
If you want to find artwork (AW), you can search on AW-* to bring up all the artwork in Agile.
You will have to browse the list to find what you are looking for.
Note:
If you want the artwork for a particular product such as DGN1000, do a search on DGN1000*, and it brings up everything that has this product in its description. The descriptions might not all have the product ID in them, but the artwork (AW) files will.
Start a Project
26
.
Production Guide
Figure 4. Search for artwork
Start a Project
27
Production Guide
Document Preparation
These steps provide a high-level outline of the procedure for getting a new doc set ready for editing. Some of the steps involve using the custom commands available on the custom
NetgearUtils menu in your FrameMaker installation. These commands are described in
Chapter 8, Custom Tools Reference
information about preparing documents for Agile archiving.

To prepare a document for editing:
1.
Get a similar document set on which to base the new document set. The engineer or lead writer can help you.
2.
Check the
ftp:://geardog.netgear.com//ngreng/4TechPubs/BaseDocs
directory for any stable and reusable write-ups that might apply to your project.
3.
Upgrade to the latest doc templates. See
4.
Make sure you get the correct compliance appendix for your product. The compliance information goes in the user or reference manual. See
5.
Installation guides:
f. Make sure the install guide has a section called Other Features at the end. See
g. Make sure the link to DoC is included in the install guide. See
on page 30 for more information.
h. Add the GNU GPL statement below DoC paragraph:
For GNU General Public License (GPL) related information, please visit
ï€
http://support.netgear.com/app/answers/detail/a_id/2649.
i. Make sure the Waste Electrical and Electronic Equipment (WEEE) text and logo are in the install guide. See
a. Make sure the language is set. You should see a white rectangle at the top of the first
on page 94 for more information.
6.
User manuals:
a. Make sure the language is set. You should see a white rectangle at the top of the first page of frontmatter.fm. See
on page 94 for more information.
b. Make sure page 2 (inside front cover of frontmatter.fm) is corrected to:
Phone (Other Countries): Check the list of phone numbers at
ï€
http://support.netgear.com/app/answers/detail/a_id/984.
c. Remove the Related Docs appendix, remove the cross-references to the related docs, and add the following sentence to the first paragraph in the first chapter:
For more information about the topics covered in this manual, visit the Support website at
http://support.netgear.com
.
d. If the router can be wall-mounted, add another sentence that reads:
If you want instructions about how to wall-mount your router, see Wall-Mount Your
Router at
http://support.netgear.com/app/answers/detail/a_id/18725
.
Start a Project
28
Production Guide
7.
Run the List of Variable Definitions in Book command, described in
on page 111, to generate a report of your variables.
a. This report is saved to the Reports directory under the document directory.
b. Rename this report and save it as a record of the old variable settings for the book in case you ever need to refer back to it.
Note:
Installation guides are single documents. You can make a temporary book for the single file to use for running the tools on installation guides. However, it’s best to set the metadata directly on the file rather than with the Set PDF Metadata on Book command because the book file is not archived with the install guide.
8.
Run the Edit Variable Definitions in Book command described in
Edit Variable Definitions in Book
on page 112 to set and edit your variable definitions for the new book.
Make sure you set the Class variable based on whether your product is Class A or Class
B to populate the text in your compliance appendix. See
on page 30 for more information.
Note:
Do not delete variables that are in use. The List of Variable
Definitions in Book command, described in
on page 111, shows the variables in use.
a. Make sure you create (if necessary) and set the metadata variables with the Set PDF
Metadata for Book command, described in the Templates, Tools, & Processes User
Guide, for all documents including installation guides.
a. Run another List of Variable Definitions in Book report.
b. If you want a record of the new variable settings to refer to later, rename this report.
9.
Run the Set PDF Metadata for Book command, described in the
10.
Run the List of Graphics in Book command, described in
on page 107, to review which graphics are imported by reference and which ones are copied
so you can make sure all graphics that need to be imported are imported.
a. This report also shows where Frame is finding the graphics. It’s possible that Frame is finding graphics that are not in the local directory.
b. If you want a record of the new variable settings to refer to later, rename this report.
11.
Run the Collect Outside Graphics command, described in
on page 109, to make sure all image files for the new book are in the local directory and that
FrameMaker is pointing to them in the local directory.
a. This is especially important if you are basing the new book on files that were already on your computer or reachable network.
Start a Project
29
Production Guide
b. The reason is that even after you copy the files to a new directory, Frame continues to point to the files at the old location. When you archive the new file set, there are broken links to graphics at the old location on your computer or reachable network.
12.
Run the List of Cross-Ref Formats in Book command, described in
on page 104, to generate a report of the cross-reference settings for the
book.
a. Review the report for cross-reference consistency.
b. Rename this report and save it as record of the old cross-reference settings for the book.
13.
Run the Edit Cross-Ref Formats in Book, described in
Edit Cross-Ref Formats in Book
on page 105 to set and edit your cross-reference definitions for the new book.
Note:
Do not delete cross-references that are in use. The List of X-Ref
Definitions in Book report shows which cross-references are in use.
14.
Before you submit the book for archiving in Agile, run the Collect Outside Graphics command, described in
on page 109, one more time and finish
up by running Move Unused Graphics to prevent extra graphics from being archived with the book.
15.
Delete the reports directory.
Compliance Information
Compliance information goes in the last appendix of the user or reference manual and on the second page of the installation guide.
User Manuals
The compliance information varies depending on whether the product is wireless single band, non wireless single band, wireless dual band, or non wireless dual band. The product can also be Class A or Class B. There are four templates that you choose from based on whether the product is wireless or not and whether it is single or dual band. The Class setting is based on a book variable that you set to populate the compliance text with Class A or Class B as applicable.
Installation Guides
Make sure there is a link to the DoC on the second page under technical support or in the third panel right above the copyright information. The DoC link looks like this:
For complete DoC please visit the NETGEAR EU Declarations of Conformity website at:
ï€
http://support.netgear.com/app/answers/detail/a_id/11621/
Start a Project
30
Production Guide
The new templates are set up so that the link to the DoC is there.
WEEE Notice and Logo
The Waste Electrical and Electronic Equipment (WEEE) notice has to appear with the WEEE symbol. We put the notice and symbol on the install guides. If you see a WEEE symbol without the notice, please add the notice. The new template has the symbol and text, which are reproduced below so you know what you are looking for.
This symbol was placed in accordance with the European Union Directive 2002/96 on the Waste Electrical and Electronic
Equipment (the WEEE Directive). If disposed of within the European Union, this product should be treated and recycled in accordance with the laws of your jurisdiction implementing the WEEE Directive.
Figure 5. WEEE symbol and text
Other Features Section
For routers and DG products using the CD-less installation, the installation guide needs an
Other Features section at the end. The reason is we learned from user studies and Beta feedback that users want to have quick pointers on where to find information about how to use these features. The text should read:
For features like Live Parental Controls, Traffic Metering, ReadyShare, and Guest Access, please log in to http://www.routerlogin.net for more details.
Manuals on Docs Server
Many products have a link to the user or reference manual from their user interface or on the
CD. Currently, this link is to the
http://docs.netgear.com
server.

The writer creates the link as follows:
1.
Start VPN if you are working offsite. VPN is not necessary if you are working onsite and using an employee NETGEAR laptop.
2.
Access the docs server with the user name and password supplied by the technical
publications manager or IT. See
on page 158 for more information about
accessing the docs server.
Note:
Sometimes docs.netgear.com is not accessible, and it usually means the log file is full. Contact Kent Robinson so he knows he needs to clear out the log file at: [email protected].
3.
Create the directory structure in this format: /modelnumber/language code/part number.
Start a Project
31
Production Guide
Note:
Only Chinese, German, French, Japanese, and Korean have their own user/reference manual link with a language-specific language code. The other languages link to English manuals. The English language code is enu.
Sample URL using the English language code:
http://documentation.netgear.com/cwge111/enu/202-10634-01/index.html
4.
Give the URL to the product engineer so it can be put into the product user interface or included on the CD.
5.
Create and put index.htm and index.html pages in the directory. Get the page template from
ï€
http://docs.netgear/com/1sample-page.
a. Provide the model number and product name.
b. Fix the link to the user manual to show the correct path.
c. The manual name is always usermanual.pdf.
d. Comment out the section that does not apply. For example, if you do not have the manual to put out there yet, show the text that says, “The manual for this product will appear here soon.”
6.
Check the links with Firefox (if possible) and Internet Explorer to be sure the pages display correctly.
7.
When you have the manual ready to post, rename it usermanual.pdf and put it in the directory.
Start a Project
32
4.
Document Preparation
How to create a printed or web-based document
4
This chapter provides procedures and guidelines for preparing FrameMaker printed and online documents.
The following topics are covered in this chapter:
•
•
•
•
•
•
•
•
•
33
Production Guide
Part Numbers and Bar Codes
Everything requires a part number, but only printed documents have a bar code. There is one exception to this, and that is certification documents. Certification documents get Part#TBD until we know the project is going ahead.
Requesting Part Numbers

To create a help ticket:
1.
The lead writer opens a browser and goes to the TrackIt page:
ï€
http://trackit.netgear.com/TIWEB8/scripts/TIWebPortal/TrackItUser.asp
2.
Click Manage your Work Order Requests.
3.
Click Add a new Work Order.
4.
Fill in the fields:
Priority. Normal
Type. Document Control.
Subtype. Part Number Request.
Category. Select the Agile analyst for the product line.
Notes. Indicate which files are to be picked up and where they are.
5.
Click Submit.
Part Number Anatomy
Part numbers use this format: xxx-yyyyy-zz; for example, 202-10045-05.
Prefix (xxx): The prefix indicates the type of material or assembly type. All documents have a prefix between 200-229. Install guides use 201, user and reference manuals use 202, and setup manuals use 208 for the prefix.
Base PN (yyyyy): The base PN is sequentially assigned starting with 10000. This part of the number changes when there has been a significant change to the document.
Suffix (zz): The suffix starts with 01 and rolls for most changes. The suffix is also referred to as “the dash.”
Document Preparation
34
Production Guide
When a Document Changes
If you change a document after it has been released to Agile, in most cases you just bump the suffix up one, which is also referred to as “rolling the dash.” You might need to request a new part number if the document has changed significantly.
If a document goes on a CD and has a minor change, the CD software needs to be changed, which means the dash needs to roll on the document. However, manuals that are placed on the Web can either roll the dash or use versioning instead of rolling the dash. This means that instead of changing the part number, the document version changes. For example, Version
1.0 becomes Version 1.1 with the same part number as Version 1.0. If you change the version, the document still goes into Agile. Notify the Agile analyst that the version changed so he or she can roll the revision in Agile.
Note:
All questions regarding part numbers and when to change them are to be directed to the Agile analyst for the business unit.
Document Bar Codes
Every printed document has a bar code of the part number. Bar codes are usually placed on the master page. If you are working with a bar code that is an Illustrator file, import the image by reference, and then size in FrameMaker. Be careful not to crop off the edge of a bar code, or the bar code will not work correctly in the finished document.

To install Bar Code Wizard

1.
Go to V:\Engineering\TechnialPublications\Tools\BarCodeWizard\4.1.
2.
Double-click setup.exe.
3.
Get the name and key to use from the key.txt file.
To create the Bar Code Image File and put it in your document:

1.
Launch the Barcode Wizard
2.
Select Code 39.
3.
Enter the part number for the document.
4.
Copy the code to the clipboard.
5.
In FrameMaker go to the master page and paste the bar code into the anchored frame.
To save the bar code as an Illustrator file (not usually necessary):
1.
From Adobe Illustrator, select File > New.
2.
Use an art board size of 468 x 60.
3.
Paste the bar code (from the clipboard).
4.
Save the file to your fmsrc\img folder and use the part number for the filename.
Document Preparation
35
Production Guide
Bar Code Sizes
A question came up about the minimum size a bar code can be and still be read by the scanner. We did not find the precise smallest size, but operations provided these bar code specifications that are used on the boxes:
Form at /
S ym bol o gy
Font
C od e 39 Arial
Siz e (P t) Font
Height
(m m )
12
Ba rcode
He ight
(m m)
Narrow bar w idth
2.9
 0.5
7 .5
 0.5
2 do ts
Ra tio
2.5 : 1
Figure 6. Bar code sizes used on boxes
Barcode
W idth
(m m )
4 0
 5.0
Adjust spa ce s
0
Add a Bar Code Directly to the PDF
It’s always best to put the bar code in the source file; however, there could be a rare case when you need to put a bar code directly on the PDF so it can be loaded into Agile, but you do not have the source file.

To put the bar code directly on the PDF:
1.
Convert the bar code image to a PDF by copying it into Word, Frame, or Illustrator and saving it as a PDF.
2.
Open the PDF document into which you want the bar code image inserted.
3.
Create a button the approximate size of your bar code. You can resize later.
a. Select Forms > Add or Edit Fields, and select Yes if a dialog box displays.
b. In the upper-left corner of Acrobat Pro, select Add New Field > Button.
c. Position the button where you want the bar code to go and use the bar code number to name it.
d. Right-click the button and choose Properties.
e. Click the Options tab
f. In the Layout drop-down select Icon Only.
g. Click the Choose Icon button and select the bar code PDF.
h. Click OK.
i. In the Button Properties dialog box, select the Appearance tab to set the background and border color as needed. Usually No Color is the preferred setting.
j. Click Close.
k. To position the bar code, right-click the button and select Align, Distribute and
Center.
l. Select Forms > Close Form Editing.
4.
Save the PDF and voila!
Document Preparation
36
Production Guide
Quick Response (QR) Codes
Some of our documents are starting to use Quick Response (QR) codes to take the reader directly to a download page or somewhere else of interest. The user scans the QR code with a device such as a smart phone that has a bar code scanning application installed on it. A QR code can be a URL, text, phone number, or SMS.
The following link lets anyone make a QR code for free:
http://qrcode.kaywa.com/
This article mentions several options:
http://gadgetwise.blogs.nytimes.com/2011/03/01/qa-make-a-quick-qr-code/
This QR code takes you to
www.netgear.com
:
Figure 7. A QR code that when scanned goes to the corporate website
Print Specs
All documents destined to be printed and put in the box have a print specification, also known as a print spec. A print spec is a Word or text document that tells the printer how to print the document. The print spec is archived with the document.
NETGEAR uses printers based in Taiwan to save money. The employees read and speak
English, but are sometimes not very proficient. It is very important that the print spec be clear and contain enough details so the printer can interpret the print spec and print the document correctly.
If you have a new type of document for print, it is a good idea to come up with a preliminary print spec and work with the printers to get samples. This can save you unwelcome and expensive surprises when you find out that the print spec was not as clear as it needed to be.
on page 38 or contact the NETGEAR Operations department
to get printer names and their email addresses. It is a good idea to email two or three printers and request samples. You would include an initial print spec and a PDF of the preliminary document. You might want to cc someone at NETGEAR, preferably in Operations, who speaks Chinese because sometimes the printers respond in English and Chinese.
Operations negotiates prices with the printers and handles the logistics of getting something printed. Your goal in contacting the printers is to determine exactly how you want something printed and how the corresponding print spec should read. The final choice of the printer and price are determined by Operations after the document and print spec are uploaded to Agile.
Document Preparation
37
Production Guide
What to Specify
•
Cover paper weight. 80#, 100#, etc.
•
Inside paper weight. 80#, 100#, etc. The cover can be different from the inside.
•
Paper color. White, yellow, or whatever color you want.
•
Printing color. Specify 4 color or B&W. Router/DG install guides use 4-color print. All other install guides use B&W. Note that some localized router/DG install guides are B&W instead of 4 color. This difference is handled by the localization team.
•
Paper type. Glossy, wood-free uncoated (cheaper), or whatever you want.
•
Binding. Saddle stitch (stapled), which works well with thin documents, or perfect bound
(glued), which works well with thick documents.
•
Finished size. Specify in inches and in metric (centimeters or millimeters). Make sure the
finished size fits in the box. You can get the box dimensions from the NETGEAR packaging team.
•
Folding instructions. If the document will be folded, explain whether the document will fold accordion style, in half horizontally, in half vertically, or whatever. You can send a folded sample to the printer if the document has a complex fold.
•
Layout. Double-sided or single-sided.
Printer Contact Information
Kin-Shine (Shanghai Area)
Contact: Ryan
ï€
Tel: +886-2-2222-4656 #331
ï€
Fax +886-2-8221-5067
ï€
Email: [email protected] or [email protected]
Fudy (Dongguan and Suzhou)Contact: Milan (Suzhou)
ï€
Phone: +86-512-62716091 ext 202
ï€
Fax +86-512-62716089/90
ï€
Email: [email protected] or [email protected]
Yuto (Shenzhen and Suzhou)Address: #155, Songshan Rod, GaoXin Area, Suzhou City.
ï€
Contact: Kelly
å¼ é›ªè‰³ï€
Tel: +86-512-66627837
ï€
Fax: +86-512-68836873
ï€
Email: [email protected]
ï€
Contact: Mr. Wu (Manager, located in Suzhou)
Document Preparation
38
Production Guide
Illustrations
If new illustrations are needed for a project, they are typically created by a contract illustrator in Adobe Illustrator format. When possible, illustrations should not include callouts. Callouts are added in FrameMaker to make translation easier.
In FrameMaker, use 9 point Arial for the text and make the callout lines either 0.5 or 1 point thickness.
Note:
If you experience font problems with legacy illustrations, the
Illustrator file might have layers that previously contained text with those fonts, even if the text has been deleted. These layers should be removed to solve the problem.
Adobe Illustrator Files
Import Adobe Illustrator source files directly into your documents. Do not convert illustrator art to JPG or PNG or to any other format for your doc. There are 2 reasons for this:
•
Localization. Anything being translated whether it's a print document or a PDF should use Illustrator art so the translators do not have to redraw the illustrations.
•
Printing. Anything going to print needs to be crisp. JPGs and PNGs made from Illustrator art do not render nearly as well as simply using the illustrator art. Screen captures seem to be fine. At least we haven't had any complaints about them so far.

To use an AI file in your document:
1.
Put the Adobe Illustrator file into the /FmSrc/Img/ folder for the document.
2.
Import the file into FrameMaker by reference. Do not embed the image (except bar codes).
Accept the FrameMaker default setting of 96 dpi. Scale the graphic in Frame as needed.
AI Production Files
Adobe Illustrator art files imported directly into FrameMaker as *.ai files have a color mode, which is either CMYK (less bright colors for digital printing) or RGB (brighter colors for online viewing). It is easy to change the color mode in AI. Acrobat Pro also has features to handle color modes in case your AI file is in the wrong mode and you cannot or do not want to change the mode in Illustrator.
•
The PDF Setup dialog box that displays when you select Save as PDF, has a Convert
CMYK Colors to RGB check box at the bottom that should always be selected. See
To use the Save as PDF Command:
•
The Preflight command covered in
Prepare for Color or BW Printing (Preflight)
on page 87 converts RGB colors to CMYK for PDFs that go to the printer for digital printing.
Document Preparation
39
Production Guide
As long as you (1) have the Convert CMYK Colors to RGB check box checked for the online version, and (2) remember to run the Preflight command on the printed version, it does not matter which color mode the ai file uses. However, for documents that will be printed, CMYK color mode is preferred. Also, the color specifications used should follow the CMYK color specifications in the NETGEAR Branding Guidelines.
Note:
Writers using a 64 bit laptop, might have to leave the Convert CMYK
Colors to RGB check box deselected. There is a FrameMaker bug that prevents the PDF from generating when this check box is selected on some 64 bit laptops.

To set or change the color mode in Adobe Illustrator.
1.
Select File > Document Color Mode.
2.
Select either CMYK or RGB.
Export Graphics from .ai Files
Normally, we import Adobe Illustrator files directly into the documents. However, there might be times when you need to export graphics from .ai files.

To export graphics:
1.
Open an illustrator file in Adobe Illustrator.
2.
For backup purposes, save the file under a new name.
To save the file so that it is compatible with older versions of Illustrator, select the version from the drop-down list from the Illustrator Options screen.
3.
Delete any extraneous images from the file, or place them outside of the art board area.
This is necessary because this method exports content from the entire art board; it does not allow the option to select individual images to export.
4.
To reduce the size of the art board so that it wraps around the image:
a. Select File > Document Setup > Edit Artboards.
Document Preparation
40
Production Guide
b. Drag the corners until the border fits nicely around the image.
c. Go back to the main screen and save the file.
Edit Artboards
Resize Art board
5.
Select File > Export.
a. Select the folder in which to save the image.
b. Name the image.
c. Select the format type for the image from the drop-down list.
There are many format options from which to choose. The recommended format is
EPS or TIF because the resolution is better in printed documents.
Format options
Note:
The only format not available from this method is EPS. To save a file in EPS format, select File > Save As and select the Illustrator EPS option from the Save as type drop-down list.
Document Preparation
41
6.
Set the JPEG options
Production Guide
a. Quality. Set to 7 High.
b. Color model. Select RGB, CMYK or Grayscale.
c. Resolution. Set to at least 300 dpi.
d. Options. Keep defaults.
e. Click OK.
Note:
For all graphic formats, set the resolution to at least 300 dpi.
The graphic is now ready to use in documents.
Document Preparation
42
Production Guide
Save to an Older Version of Illustrator

To save to an older version of illustrator:
1.
Open the illustrator file and select File > Save As.
2.
From the Illustrator Options screen, select the version from the drop-down list.
3.
Set the other parameters, as needed.
4.
Click Ok.
Scale Illustrations

To scale illustrations:
1.
Open an Illustrator file.
2.
Select the entire image that you want to scale.
3.
You can do either of the following:
-
Select Object > Transform > Scale.
-
Uniform. Use this option to proportionally scale the image.
Document Preparation
43
Production Guide
-
Non-Uniform. Use this option to individually change the width and height of the image.
-
Options. Use with the non-uniform option to set the stroke on an object proportional when you size it up or size it down.
f. Select the Scale tool.
The dialog box displays, but you can size the image up or down by dragging the image from corner.
Scale
Tool
Product Photos
User manuals and reference manuals include a product photo on the front cover. Product photos are located on Mediabin (
https://mediabin.netgear.com
) and on the V drive. If they are very recent, they can sometimes also be found at
ftp://geardog.netgear.com
.
If you cannot get the product photo you need but you have the unit, you can have an illustrator take photos and make an illustration from the photo.
Sometimes you need a product illustration early for a Beta document before there are any units to photograph and before any photos are available on Mediabin or geardog. In that case, look for early artwork that will be used to make the units in either of the following two places. This artwork can be used to figure out where the ports and cables ultimately go when the unit is made. Label artwork indicates the location of DSL and Ethernet ports, for example.
V:\Current Projects\DGND3700\DGND3700 V1H1 ENCLOSURE ARTWORK
ï€
V:\Marketing\Product Files\<product model>
Document Preparation
44
Production Guide
Screen Shots
Always create screen shot images used in any Frame project by first getting the image (do a screen capture, take a digital photo, or get the image from an engineer), and then preparing the image. You can use a screen capture program such as SnagIt, Print Screen, or
RoboScreenCapture, which is in FrameMaker 9 under the File menu when you have a file open. Both SnagIt and RoboScreenCapture have a scrolling feature, which can be more convenient than Print Screen, which does not. See also
Use WinTV to Get Screen Shots from a TV Display

To use PrintScreen:

1.
Press Ctrl+Print Screen, Alt+PrintScreen, or Fn+Print Screen depending on your PC and operating system. This way you capture only the active window instead of the entire desktop if you use only PrintScreen.
2.
Open Microsoft Paint or Adobe Photoshop.
3.
Select Edit > Paste or use Ctrl-V to paste the image.
4.
Save the file in the /FmSrc/Img/ImgScr folder for the document with a unique file name in the default file format. You can create a subfolder for screen shots if it helps you stay organized.
To use RoboScreenCapture
1.
In Frame select File > Launch RoboScreenCapture.
2.
In RoboScreenCapture, select the Capture menu and the most appropriate option for capturing the image.
3.
Save the capture as a JPG.
Note:
If engineering provided screen shots and they are low resolution, you might have better luck with the .png format than a .jpg.

To prepare and Combine Screen Captures
Prepare a screen capture for a document within FrameMaker using RoboScreenCapture and the Graphics toolbar.
1.
In Frame select File > Launch RoboScreenCapture.
2.
Open the file you want to prepare and select File > Open.
3.
Select Capture > Capture Settings > Crop & Scale to adjust the image as needed.
4.
Select Capture > Capture Settings > View & Edit to combine images or portions of a GUI screen into a single image. See also
Combine Screen Captures with Photoshop
5.
Save the image.
6.
Import the image into FrameMaker. See
Import Screen Captures into FrameMaker
7.
Within FrameMaker, put a 1 pt. black border around the image within FrameMaker. Use Pen
Pattern 0, and check that the borders are consistent, clear, and crisp throughout the PDF.
Document Preparation
45
Production Guide
Borders
Set borders around graphics, such as screenshots from within FrameMaker. Apply a 1-point solid black pen pattern. No shadow is needed. We do not usually put a border around illustrations.

To set borders within FrameMaker:
1.
Set the line width to 1.0.
2.
Set the selected color to black.
3.
Select the screen capture.
4.
Select Pattern 0. from the Pen Pattern drop-down .
Set Line Width to 1.0
Set color to black
Select pen pattern
0 from drop-down
When the border is added within FrameMaker, it is not resized with the graphic, but maintains a consistent size throughout the document. Also, applying the borders within
FrameMaker makes it easy for someone else to change or remove the border if needed.
Note:
If you have a book with a lot of screen captures done in the old style, it is okay to leave them as is until a later time when there are more resources to handle converting the borders.
Import Screen Captures into FrameMaker
•
Import by reference. Do not embed graphic files.
•
Use an image file format compatible with FrameMaker like .jpg, .eps, or .png. In
Photoshop use the Save for Web feature to create .jpg files. For documents with a large number of images, use only jpg files because .eps and .png files use more memory.
•
Import the image file into the Anchored Frame in FrameMaker, accepting the default custom dpi settings (usually 96).
•
In FrameMaker, reduce the graphic using Graphics > Scale. Typically, 50% works well for screen shots.
Use a Dedicated Laptop for Screen Captures
To get screen captures from a NETGEAR product user interface, you need to connect the product to a laptop that is connected to the Internet. Do not connect the NETGEAR product to
Document Preparation
46
Production Guide
your work laptop so you can keep it free for working and also to prevent anything unexpected happening if the NETGEAR product is not production ready.
Ask the technical publications manager to get you a NETGEAR laptop that you can dedicate to hooking up to NETGEAR products for screen captures. This laptop does not have applications software on it, but might have Gadwin PrintScreen. If not, you can put a screen capture program on it if you like, or you can use the Print Screen method described in
on page 45 for getting screen captures.
Combine Screen Captures with Photoshop
You can use RoboScreenCapture to combine screen-captured images from portions of a GUI
display (such as the top half and the bottom half) as described in
on page 45. You can also do it in Photoshop 7 or later as described here.

To combine screen captures:
1.
First, flatten the layers (Layer menu > Flatten Image option).
Double-click on the background layer to create a new layer. (If the Layers window is not open, select Window > Layer, and then double-click Background).
2.
Add the borders.
a. Crop the top screen shot just inside the borders.
b. Select Photoshop Image > Canvas Size
c. Set the anchor to the direction you want to enlarge the canvas. For example, clicking the top arrow positions the anchor so that the increase will add to the bottom when you increase the height.
d. Increase the height. If both source images are about the same size, you can double the height.
e. Paste a copy of the second cropped image, and drag it to the newly enlarged canvas by holding down the <Ctrl> key while using the mouse to drag the image into alignment with the upper portion .
f. If necessary, crop the new composite image.
Document Preparation
47
Production Guide
3.
Save the image as a .psd in the /FmSrc/Img/ImgeSrc folder.
4.
Prepare the image and save it as described in
To prepare and Combine Screen Captures
Use WinTV to Get Screen Shots from a TV Display
This method is used primarily to get screen shots of EVA or NeoTV menus that are displayed on the TV screen. To avoid copyright infringement, do not take screen captures of scenes from videos or movies.
You need a Windows-based PC, Win TV software, the Win TV USB device, and the AV cable from the Win TV package. To connect the EVA unit you need either a composite video cable or an S/PDIF cable. The quality will be better with S/PDIF, but composite generates an image acceptable for a user manual.
WinTV is not compatible with HDMI, which yields the best image quality. HDMI screen captures require a card installed inside a computer as opposed to the USB connection that
WinTV provides. If a higher-resolution image is required, Michael Ellis has an HDMI set up in the lab, and can provide screen shots.
Setup
•
If you need media files to populate your screen shots, you can use content located on the
V drive in Current Projects/EVA Media Files. Copy the files onto a shared folder on the PC that is on the same network as EVA (an Ethernet connection to a router is easiest). See the EVA documentation about setting up network shares so that EVA will locate the media files. You can put them on the same PC that you will use to get the screen shots.
•
The EVA unit must be connected and working.
•
Make sure that the EVA unit is not connected with HDMI cable. If it is connected with both composite video cable and HDMI, EVA will communicate with HDMI and you will not be able to get screen captures.
•
Make sure that the TV is set to the right mode (AV mode for composite video) so that you will be able to see the TV display. Cycle through modes if you need to until you get a display (see the EVA IG).

WinTV Installation
To use WinTV:
1.
Go to the Hauppauge website and download the most recent WinTV software.
2.
Insert the WinTV USB device into a USB port on your computer and connect the WinTV AV cable to the USB device.
3.
Go to the TV and disconnect the EVA composite or S/PDIF cable from the TV. You bypass the TV completely while getting screen captures.)
4.
Connect the composite or S/PDIF cable to the Win TV AV cable. The composite cable connects to the small port on the side of the WinTV USB device.
5.
Follow the WinTV instructions to install the WinTV software.
Document Preparation
48
Production Guide
The WinTV installation process installs a WinTV user manual on your local computer. Follow the instructions in the WinTV user manual to get screen captures.
On some laptops, Photoshop locks up when WinTV is running. In this case, you can use
Alt+PrintScreen to capture images, past them into Microsoft Paint, and then save them.
Adjusting Screen Capture Proportions

The screen captures looked a bit squeezed (taller and skinnier than the EVA TV display).
To adjust properties in Photoshop:
1.
First, deal with cropping, resolution, and size. Crop the image if needed to remove the
WinTV border.
2.
In Photoshop, select Image > Image Size, and click Auto to improve the resolution. Change the width to 3 inches.
3.
Select Image > Image Size to fix the tall, skinny problem. Clear the Constrain Proportions checkbox. Reduce the height (enter a lower value in the Height field and press Enter).
Now you can prepare the screen shot image file as described in
Update Screen Shots When Product Name Changed
If you need to update screenshots when updating manuals for a new product name, there are new GUI banner files for most products in this type of directory:
V:\Marketing\Product Files\DGN1000\GUI Banners
Just look under the appropriate product. Then cut and paste the new “top of the screen” so that it shows the new product name. Sometimes you can crop off the product name entirely. It depends on the GUI.
IP Addresses
When you provide an example IP address in a document, do not inadvertently use a “live” IP address. This is to prevent the unintentional use by customers of valid IP addresses that are either in use or reserved. For a list of reserved IP addresses, see
http://en.wikipedia.org/wiki/Reserved_IP_addresses
.
Document Preparation
49
Production Guide
FrameMaker
This section describes guidelines for creating FrameMaker documents. See also the
Templates, Tools, & Processes User Guide for detailed information on chapter, paragraph, and variable definitions.
Templates
The templates are available on the FTP site in the 4TechPubs folder and also at
V:\engineering\TechnicalPublications.
We often use existing books as the basis for a new book. If the existing book uses an older template, please convert to the new template before proceeding. See
Chapter 9, Old Style to New Conversion Tutorial
for information about how to handle variables when you convert.
Installing Fonts

To install Futura fonts:
1.
Close FrameMaker.
2.
Copy the 4TechPubs/Fonts/FuturaNewTemplateFonts folder from geardog to your desktop.
3.
On your PC, open the Control Panel and select Fonts.
4.
Move the fonts into the Fonts directory:
a. Windows XP. Open each folder within the Futura directory and drag-and-drop the individual fonts (not their folders) into your Control Panel Fonts folder.
b. Windows 7. Right-click the font and select Install or use the Copy and Paste commands.
5.
Double-click FuturaFonts.exe to install the remaining Futura fonts. The .exe file contains HP
Futura fonts, but does not let you see which ones. The only way to get them is to execute this file.
Stop the Font Substitution
If FrameMaker is substituting a font and you want it to remember the substituted font, there is a way to do that. For example, if FrameMaker is substituting Times New Roman for Times
Roman, you probably want it to just use Times New Roman all the time.

To stop font substitutions:
1.
Open the file that gives you the Unavailable Fonts message.
2.
Make sure you want FrameMaker to use the substituted font.
3.
Select File > Preference > General.
4.
Clear the Remember Missing Fonts check box.
5.
Click Set.
Document Preparation
50
Production Guide
6.
Save the file and open it again. This time FrameMaker does the substitution without remembering the old font.
7.
Save the file again and you are all set.
8.
Go back and select the Remember Missing Fonts check box. This is so that if another font goes missing that you need and FrameMaker does a substitution, the substituted font is not remembered.
Vardefs File
Historically, technical publications has used a vardefs.fm file for managing document variables. It is a Frame file with a two-row table. Left column lists the names of all the document variables for the book, and the right column lists their definitions. To update the book using a vardefs file instead of the preferred Edit Variable Definitions in Book command:

To update variables with a vardefs file:
1.
Open the vardefs file.
2.
Edit the definitions as needed.
3.
To add a variable, make a new row in the table and add the name and definition and select
Special > Variables to add it to the Variables tool also.
4.
To delete a variable, delete the row in the table and select Special > Variables to delete it from the Variables tool also.
5.
Update the book variables by doing the following:
a. Select the book.
b. Select Edit > Select > All.
c. Select File > Import > Formats.
d. In the drop-down list select vardefs.fm.
e. Deselect everything except Variable Definitions in the Import and Update box.
f. Click Import.
Frame takes the variable definitions in vardefs.fm and applies them to the book.
Note:
With the Edit Variable Definitions in Book command, it is no longer necessary to use a vardefs file. However, writers are welcome to continue using it if they prefer. The procedure descriptions in this guide other than in this immediate section provide instructions for using the tools and not the vardefs.fm file.
Document Preparation
51
Production Guide
Set Up a FrameMaker Book without Blank Pages

To eliminate blank pages:
1.
Open the book in FrameMaker. You might need to change the settings for each file in the book.
2.
Right-click the file and select Pagination.
3.
In the 1st Page Side field, select Next Available.
4.
In the Before Saving & Printing field, select Delete Empty Pages.
5.
Click the Set button.
6.
Save the book to retain the changes.
Add a Child Book
You can add books within books. The books can be unstructured book files or DITA maps.
A child book is treated as a placeholder within the parent book. You cannot edit a child book from within the parent book view. All maintenance tasks must be performed in the child book separately. For example, any book-wide operation on the parent book, such as spell check or find/replace works only on parent book files and not on the child book files. You should search and update child books separately.
Similarly, when updating a parent book for pagination and cross-references, ensure that you first update the child books and then update the parent book. This is because numbering and pagination information is stored at a book level. A book update on the parent book does not affect the page numbering within the files in a child book if the files in the child book are closed.
However, if the files from the child book are already open, they are updated but not saved.
You should always explicitly save all open files after a book update command or after applying a book-wide command.

To include multiple child books at multiple levels in a book:
1.
Open the parent book into which you want to add a child book.
2.
In the book window, select Add > Files.
Document Preparation
52
Production Guide
3.
Navigate to and select the book file you want to add as a child book.
4.
Click the Add button.
5.
Double-click the child book to open it in a separate Resource Manager panel.
Note:
You can click the Browse URL button in the Add File dialog box to select a book residing on a WebDAV server.
Make a PDF of Parent and Child Books
When you save a parent book file as a PDF, FrameMaker updates information for only those files that belong to the parent book.

To ensure that the information is correctly represented in the PDF for child books as well, do one of the following:
•
First update all child books and then their parent books before saving a book file as a
PDF.
•
Open all files, including the files in the child books before saving the parent book file as a
PDF. After creating the PDF, ensure that you save all the open files to preserve any updates.
Disconnected Pages
The visual install guide, also called a place mat, is used for routers. It has two pages. The first page is an Adobe Illustrator drawing showing how to connect the router, and the second page is three columns of text that walk the user through installation. The first page of the place mat uses a disconnected page for the Adobe Illustrator art. A disconnected page means that page’s content does not flow to the next page.

To add a disconnected page:
1.
Select Special > Add Disconnected Pages.
2.
Complete the dialog box.
3.
Click Add.
Document Preparation
53
Production Guide
Links to Internet Resources
For links to support within a document, use
http://support.netgear.com/
. This automatically takes the user to the kbserver website.
Note:
It is okay to put links in our documents to Internet resources that are not owned by NETGEAR, but this should be done with discretion. It is fine to link to technical standards or organizations such as IEEE. In general, do not link to commercial documents owned by competitors or other private companies.

To link to an Internet resource:
Note:
See also
URL Tools on page 115 for a faster and more accurate
tools-based approach to linking.
1.
Type the destination URL, or text such as click here, into the FrameMaker file.
2.
Select and tag the URL or text with the Jump character format.
3.
Select the URL and then select Special > Hypertext.
4.
In the Command pull-down, select Go to URL.
5.
In the text box after message URL, type the URL into the text field.
6.
Select New Hypertext Marker.
7.
Select Format > Document PDF Setup and check that the Create Named Destinations for all Paragraphs check box is selected.
8.
Save the Frame file and make a PDF.
9.
Check the link by positioning the mouse pointer over the link to view it.
10.
In the PDF, select the link to make sure it is active and goes to the correct web page.
Turn Off Annoying Warnings

To turn off those annoying warnings in FrameMaker:
1.
Select File > Preferences > General
2.
Clear the Show warnings while clearing history check box or
3.
Select the Show warnings while clearing history and Once for every history clearing
command check boxes.
Document Preparation
54
Production Guide
Import Text Files into FrameMaker
Sometimes a text file that you want to import into Frame was edited in such a way that the edits create lines that are not formatted correctly.

To fix the spacing:
Change the spaces in the bad lines to “[Esc] [space] 1" to replace with a figure space. This corrects the spacing
Note:
The Global \x20 => \x10 changes the space character to a numeric space (in hex).
Change Bars
You can turn change bars on and off through the FrameMaker menu system or by using key commands, as follows:

To use the Format Menu

1.
Select all chapters in the book.
1.
Select Format > Document > Change Bars to display the Change Bar Properties dialog box.
2.
Select either Automatic Change Bars or Clear All Change Bars as applicable,
To use Key Commands
1.
Select all chapters in the book.
1.
Hold the Esc key.
2.
Press c and then h (Esc + c, h).
Document Preparation
55
Production Guide
Anchored Frames

Always place artwork and screen captures inside anchored frames.
To add an anchored frame:
1.
When you use the Below Current Line setting, it is best to right-align the frame and then size it to the paragraph text above it, as in the following example. It might also be useful to use the anchor tag as a spacer after the text.
•
A best practice for an anchored frame is to set it to Below Current Line/Right.
•
For the width, 6.25’ aligns with p1_body, and 6.0” aligns with the step.
•
Use figure captions except within procedures. When you use them, do not use periods at the end.
2.
There might be times when centering the graphic might look better, like when it’s a complicated illustration. Adding a figure caption mostly like will not work in these situations.
Internet
Document Preparation
56
Production Guide
Graphics
Although FrameMaker can import many graphic formats, the graphic formats typically used in
NETGEAR documentation are:
•
JPEG. Good overall.
•
PNG. Good for screen shots and text.
•
EPS. Good for printing, but are not visible in thumbnail view on Windows.
•
AI. Good for illustrations. Where possible import AI files directly into FrameMaker. The resolution is better and it’s easier for localization.
•
GIF. Good for cases where there are solid blocks in images.
When you add graphics, use the Object Properties feature to scale them appropriately.
Callout Text
See Minimalistic Callouts Heighten Visual Appeal at
http://idratherbewriting.com/2011/01/17/minimalistic-callouts-heighten-visual-appeal/
for tips on writing and placing effective callouts.
For callout text, use Arial, 10 pt bold.
There are two ways to add callout text:
This is a “Text Frame” feature, which allows you to add the
CallOut paragraph tag.
This is the “A” feature in Frame.
Figure 8. Add callout text to figure
•
Draw a Text Line feature (“A” on the menu).
This feature is good for one-line callouts, and needs to be manually formatted. You need to manually change the font to the size, color, and text option (bold, italic, etc.) that you want to use.
•
Place a Text Frame feature. (“Page” icon on the menu).
This feature allows you to add a paragraph tag. Use the CallOut paragraph tag when using this feature. This is good when you have more than one line. The text frame can easily be sized to fit, as needed.
Document Preparation
57
Production Guide
Lines, Arrows, Color
It is preferable to use black, straight lines when pointing to an object on a figure, but if required, use arrows.
This is the 70/16/12 arrowhead size.
This is the 90/16/12 arrowhead size.
Figure 9. Pointing to objects on a figure
•
Line width. 1.0 preferred, but use .5 to 2.0, as needed.
•
Arrowhead. 90/16/12 or 70/16/12.
•
Text color. Black, but red, yellow or white can be used to make it show up on the page.
Numbering Issues
Sometimes chapters, pages, figures, footnotes, or tables stop numbering sequentially. When this happens, make sure the document numbering settings are correct. Table numbering is a little less obvious so the following procedure explains how to make your table numbers sequential. See
Finalize the Book File Set in FrameMaker
on page 127 for more information
on the numbering properties.

To make tables number sequentially:
1.
Open the book file.
2.
Select (but do not open) the chapter that has the numbering problem.
3.
Right-click the mouse and choose Numbering to open the Numbering Properties dialog box.
4.
Select the Paragraph tab.
5.
Select the Continue Numbering from Previous Para in Book radio button.
6.
Click Set.
7.
Repeat for all subsequent chapters in the book.
8.
Save and regenerate the book file.
Note:
If this does not fix it, repeat the steps above on all of the chapters prior to the chapter with the problem.
Document Preparation
58
Production Guide
Spelling, Grammar, and Style Checks
Use the FrameMaker Edit > Spelling Checker command to check your document for spelling errors before reviews and when finalizing it. Although FrameMaker does not have a grammar or style checker, you can use Microsoft Word to check grammar and basic style.
FrameMaker to Word through PDF
Word cannot read FrameMaker files, but you can easily convert a PDF to Word format. For large FrameMaker books, it might work better to make a PDF for each chapter in the book and check them individually, rather than one large PDF for the entire book. If the PDF is too large, it makes a large Word file that Word can have trouble handling

To save the PDF to a Word Document

1.
Select File > Save As.
2.
Select Microsoft Word Document *.doc in the Save as Type.
3.
Click Save.
To configure Word to check for Grammar and Style
1.
Click the Review tab.
2.
Select Spelling & Grammar in the far left.
3.
In the Spelling & Grammar dialog box, select the Readability check box to get readability statistics at the end of the check: Passive, Flesch Reading Ease, and Flesh-Kincaid grade level. See
http://simple.wikipedia.org/wiki/Flesch_Reading_Ease
for more information.
4.
In the same dialog box, click Options in the bottom left.
5.
Under When correcting spelling and grammar in Word, in the Writing Style list, select
Grammar & Style.
6.
Click Settings.
7.
Select the style settings you want.
8.
Click OK
9.
Click OK again
10.
Use the Spelling and Grammar checker.
Readability Check Caveats
The readability rating tools in Word are for general text. We write for a variety of audiences from the average to the highly technical. We sometimes have requirements for long nouns and long verbs.
The rating tools are only a guide. We can use simple, short sentence structure to improve readability and clarity. This can be done even when the words themselves are long.
There is nothing wrong with scoring a high grade level as long as the reader can easily understand the text. A manual is a composition of art and text presented so the reader can
Document Preparation
59
Production Guide
easily understand it. Everything plays a part, typeface, size, line measure, page layout, concept flow, and so on.
I have written user and programmer manuals totaling 1400 pages for a very complex software application. Similar procedures were written using similar text, and so on. The manuals used the same conventions and style for text and standardized art. Only the nouns and verbs changed. Total vocabulary of about 100 words. The goal was to have a reader say,
“This doesn't seem difficult.”, “I get it.”
Process Summary
This section summarizes the important art, compliance, editing, localization, and documentation quality standards.
Art
Import all AI art d by reference into your FrameMaker files:
1.
Cost savings. This saves money for localization. They explicitly requested that we do this.
2.
Printing. This makes the art in printed documents crisper.
3.
Efficiency. If you need to change the art, you can double-click it from inside Frame. It opens in Adobe Illustrator where you can edit it. When you save the AI file, your Frame file updates.
4.
Efficiency. Making a screen capture of an ai file not only defeats all of the above, but adds an extra step to your job. The extra step gets repeated every time you change the art.
5.
PDFs. Using the source art (ai file) displays more clearly in a PDF too. You can't tell from
Frame because Frame handles some types of art at a lower resolution to save memory.
That's why it doesn't necessarily look that good to you in Frame. It renders more clearly in a
PDF and in printed documents.
Compliance
Check with the compliance engineer on all compliance issues. This includes when engineers ask you to change a compliance appendix that the compliance engineer provided to us.
1.
Required. Some compliance paragraphs, links, and text are required to be in the docs.
The links to DoC and GPL are two examples. There is also now safety text and some other things.
2.
Costs. If someone asks you to remove compliance sections, don't do it without checking with Mark first. We can be fined (and have been fined) a lot of money by European countries when they find out that we have not complied with their rules.
Document Preparation
60
Production Guide
Printing
To get the best end result in the printed doc:
1.
Submit High-Resolution PDFs with printer marks.
2.
Include an accurate print spec.
3.
Use AI files for all illustrations.
4.
Run the PDF through preflight using the correct B&W or Color settings depending on the file.
Editing
Get all of your documents edited. Editing saves money and ensures a better user experience.
1.
Priority. IGs and other printed documents have the highest priority with editing.
2.
Cost savings. Get it right the first time rather than fix a typo, roll the dash, and resubmit to
Agile. Printed docs that are localized do not have to be retranslated when they are done right the first time.
Localization
All of these policies help keep localization costs lower:
1.
Art. Import AI files directly into FrameMaker for illustrations.
2.
Callouts. Do not embed text in illustrations. It’s more expensive to translate text that is embedded in illustrations.
3.
Terms. Use consistent terminology throughout a document as much as possible. For example all of these mean the same thing, but require extra translation time and increase costs if they are used interchangeably throughout a doc:
a. Type routerlogin.net
b. Enter routerlogin.net
c. Browse to routerlogin.net
Overall doc quality
When someone wants you to add or change text, you do not have to do it exactly as they tell you to. As a writer and a lead, you own the final words and the final presentation. Your docs go directly to a lot of non-technical consumers. You are their advocate for docs usability.
Don't let the docs become cluttered, unclear, and evolve to an unpleasing visual presentation because people ask you to add things to them.
1.
You can work with the person to find a good solution.
2.
You can propose solutions to them and discuss the pros and cons with them.
3.
If you have a problem, bring it to me. I can either help you figure out a better layout or talk to whoever it is that's insisting you add text and other visuals exactly the way they want it when it's not the best approach for our customer.
Document Preparation
61
5.
Document Reviews
Review strategies vary by project schedules
5
This chapter covers how to conduct document reviews. Schedules and cycles can vary depending on the kind of product, type of document, and business conditions. For example, sometimes documents have to be created or turned around quickly to meet changing market demands. See
on page 99 for information about the tasks involved in
preparing PDFs for review.
The following topics are covered in this chapter:
•
•
•
Fast Track Review Schedule for Wireless Adapters
•
•
62
Production Guide
Review Cycles
PDFs are emailed to reviewers as described in
documents have three review cycles before they are released. Sometimes there is not enough time in the schedule for three reviews.
Note:
When documents are requested for Beta, they get a technical review before they are submitted for testing.
•
First review. Developmental review
The writer produces a first draft and sends it out as a PDF file for a first review. The major review focus is the purpose, scope, fit for customer profile, and structure of the content.
•
Second review. Technical review
The writer turns on change bars in FrameMaker and incorporates any changes from the developmental review cycle. The revised PDF is sent for a review. The focus of the review is the accuracy and completeness of the content.
•
Final review. Release approval
The writer incorporates any changes and sends out the final draft for approval to release.
The structure, completeness, and accuracy should be final with no changes required.
When an existing document is updated or modified, usually the developmental review can be omitted. If major, substantive changes are made to an existing document, then the developmental review should be included.
At the discretion of the writer, interim updated drafts can be circulated. Even if it is a limited distribution, the writer should still use the same review cycle names and include the date of the draft in the file name.
Review Schedule
The standard time given to reviewers for each review cycle depends on the length of the document:
•
Less than 50 pages: two days per review.
•
50 or more pages: four days per review.
Some projects are fast track, or rush. Fast track projects have aggressive schedules with short review cycles and a high priority. This can be due to market demands such as compatibility with a new operating system, or getting a product to market before a competitor.
Rush jobs are urgent reactions to unforeseen circumstances. They can be unexpected, and might be needed to correct a defect that leaves NETGEAR exposed. These are rare.
See
on page 24 for algorithms to determine when a document has
to be completed to meet localization (if applicable) and shipment schedules.
Document Reviews
63
Production Guide
Fast Track Review Schedule for Wireless Adapters
Wireless adapter products sometimes have fast track schedules. Typically this is for an existing product, or a new product with the same form factor as an existing product. No developmental review is needed.
The start date is either upon receipt of a working, stable GUI-frozen product, or when the engineer identifies the wizard and provides screen shots. The writer also needs the part numbers for the documents, the product name, and the list of reviewers. The fast track documentation schedule goes something like this:
•
Day 1: Writer creates the QIG and sends it out for technical review.
•
Day 2: One-day review cycle for the QIG. (The writer can set up vardefs, etc. for the UM.)
•
Day 3: Writer corrects the QIG and sends it out for release approval.
•
Day 4: One-day review cycle for the QIG. Writer creates the UM incorporating content applicable to the custom installation flow, if applicable, and sends out the UM for a technical review.
•
Day 5: One-day review cycle for the UM. Writer makes final changes to the QIG and delivers the final PDF/file archive.
•
Day 6: Writer corrects the UM and sends it out for release approval.
•
Day 7: One-day review cycle for the UM.
•
Day 8: Writer makes final changes to the UM and delivers the final PDF/file archive.
Very rarely, for a super fast track, the QIG and UM can be sent out for review on the same day. Here is an example of that schedule:
•
Day 1: Writer creates the QIG and UM and sends them out for technical review.
•
Day 2: One-day review cycle.
•
Day 3: Writer corrects the QIG and UM and sends them out for release approval.
•
Day 4: One-day review cycle.
•
Day 5: Writer makes final changes to the QIG and the UM and delivers final PDFs/file archives.
This makes it possible to deliver both docs in 5 working days instead of 8. In this case, if changes are required in the QIG, then the writer might need to make parallel changes in the
User Manual custom installation flow. It requires a bit more work, but is the fastest schedule.
Distribution
At the start of the project, the lead writer confirms with the project manager that the review distribution is correct for the project. It should include at least these team members, although some projects include additional reviewers:
•
Project engineer. Reviews for technical accuracy, structure, regulatory compliance for target markets, and completeness of content.
Document Reviews
64
Production Guide
•
Technical support. Reviews for technical accuracy, appropriateness for the target audience, customer profile, that the content, addresses previous product call histories, and that information on how to obtain technical support is present.
•
PLM (marketing). Reviews appropriateness for the target audience, product definition, product name, feature/function product requirements.
•
Lead writer. Depending on the project, this can be a courtesy cc, or comments can be provided to the writer.
•
Editor. Checks for style guide compliance, presence of metadata on the PDF, correct compliance information in QIGs and UMs, and other things.
•
Compliance. Reviews regulatory compliance for target markets for user manuals and
reference manuals only.
Reviewer Response
Reviewers typically respond by email, but in some cases meet with writers to discuss changes.
Comment Acceptance
Comments on technical errors in the documentation are incorporated. Comments on technical completeness are accepted or rejected depending on the scope and intent of the documentation or as interpreted by the writer, lead writer, or manager. Comments on the purpose and scope of the manual, including the intended audience, are accepted or rejected based on the related material in the PRD, which is the P1 presentation. Comments on editorial style, organization, or cosmetic changes should be accepted or rejected based on
NETGEAR style and design guidelines.
Note:
Notify the technical publications manager or the lead writer if review comments cause the scope of the document to change dramatically.
Document Approval
Email responses from the reviewers are treated as an electronic signature approving the release. If there is no reply from a team member regarding a document within the allowed time frames, we take that to mean acceptance and approval of the document.
Document Reviews
65
6.
Finalize Documents
Checklists help you remember all of the details
6
NETGEAR writing projects have a lot of details that need to be attended to before the set is ready for Agile archiving. This chapter provides checklists and supporting information to help you remember all of the many details.
The following topics are covered in this chapter:
•
•
•
•
•
Final Hand-Off from Offsite Writers
•
Completed Projects That Do Not Go into Agile
•
•
66
Production Guide
Writer’s Checklists
Writers use these checklists to ensure that a document is ready for release.
URLS
Change URLs that reference kb, such as
http://kb.netgear.com/
to use support instead:
http://kb.netgear.com/.
Check the link after you change it. If it does not work, let Carlota Sage in Tech Support know.
Base Documents
If you have any write-ups that are reviewed and stable, and can be used by other writers, post them to the Base docs folder at
ftp://geardog.netgear.com//ngreng/4TechPubs/BaseDoc
, include a readme.txt file to explain what it is, and notify the writing team.
FrameMaker
FrameMaker Check
Change bars removed:
1. Select all the files in the book
2. Format > Document > Change Bars
3. Choose Clear Change Bars
4. Click OK
Pagination:
• Sequential where the cover is page 1, but the number is invisible on this page
• Blank pages removed.
Header/footer
• Running header on right with model name, model number.
• Running left-right footers with chapter/appendix number and title.
Links:
• Check links.
• Check cross-references and verify that they don’t go to a chapter in another book.
• Check TOC.
• Check index.
Metadata:
• Add metadata with variables and the Set PDF Metadata for Book command described in
Finalize Documents
67
Production Guide
FrameMaker Check
Language code:
• Add the text box with the language pdf mark as described in
Corrected phone (Other Countries) in Tech Support Section, page 2 of frontmatter.fm
• Make sure Phone (Other Countries) reads as shown and points to the link. It should not refer users to the tech support card.
Phone (US & Canada only): 1-888-NETGEAR
Phone (Other Countries): Check the list of phone numbers at
http://support.netgear.com/app/answers/detail/a_id/984
Document
Check
Editing:
• Document has been edited. See
details on what and when to edit.
Cover is correct:
• Date on cover
• Check model name, number, and image
ï€
Check manual type (User Manual, Setup Manual, etc.)
Part number:
• Check cover
• Check the dash “-0x”
Revision history (can be omitted in home products with the writer’s discretion):
• Updated
• Kept to 4 lines or fewer
List of box contents:
• Is correct
• Does not list a warranty card (this is no longer in the box, but now on the Web)
Organization:
• Cover
• Front matter
• Table of Contents
• Chapters
• Appendices
• Noise table in second-to-last appendix (wireless products only)
• Compliance info in last appendix must be correct for the product. See
• Index
Finalize Documents
68
Production Guide
Check
Art:
• Check that art is being read in from the local directory.
• Check that correct art is in the right place.
• Check that art is properly introduced in the text right before.
• Check for good quality rendering.
Printed IGs, fliers, and whatnot:
• PDF optimized for color or black and white (as applicable).
• Select Advanced > Preflight > Digital Printing > Digital Printing (Color) or Digital Printing (B\W).
• Click Analyze and Fix.
• Print spec is current and matches your doc.
• PDF with crop marks.
Online manuals:
• Save as PDF with the Convert CMYK colors to RGB box selected.
Content (Routers/DG Only)
Check
Check the, “Adding Both WPS and Non-WPS Clients” section and make sure it does not tell the reader to reset to factory default as the first step. This is incorrect information and should be removed.
Remove cross-references to online docs.
• Remove cross-references to related documents in Supplemental Information appendix.
• Remove list of related documents in Supplemental Information appendix.
• Remove “Wall-Mounting a Router” in the Supplemental Information appendix.
• Add to the first page of the first chapter in the book a statement something like this: For more information about the topics covered in this manual, visit the Support website at
http://support.netgear.com.
• If the router can be wall-mounted, add another sentence that reads: “If you want instructions about how to wall-mount your router, see Wall-Mount Your Router at http://support.netgear.com/app/answers/detail/a_id/18725.”
One appendix called Supplemental Information that contains Tech Specs and Factory Defaults.
Make sure that the two paragraphs with links to DoC and GPL are the last items on the bottom of the third panel of the second page of IGs.
Finalize Documents
69
Production Guide
Preset Security (Router/DG Only)
Table 1. Install Guides
Check
Change the WPA/WPA2-PSK passphrase to Network Key (Password). This applies to product label and references within the documentation.
Add an Other Features section to the end of installation guides using the CD-less installation.
Other Features (H1)
For features like Live Parental Controls, Traffic Metering, ReadyShare, and Guest Access, please log in to
http://www.routerlogin.net for more details.
Add this to the IG below DoC paragraph:
For GNU General Public License (GPL) related information, please see
http://support.netgear.com/app/answers/detail/a_id/2649
Preset Security Manuals (Router/DG Only)
Refer to the WA/WPA2-PSK passphrase as the network key (password).
Compliance, GNU License, WEEE Notice, Warnings
Check
Noise table
• Applies to wireless products only
• Goes in UM or RM when there is no UM. If set has both a UM and an RM, put the noise table in the UM.
• Put it right after the compliance information, which is inside the front cover (old template) or in the last appendix (new template).
Compliance Info (IGs):
• All IGs have this text either in Tech Support section or near the copyright:
For complete DoC please visit the NETGEAR EU Declarations of Conformity website at:?
http://support.netgear.com/app/answers/detail/a_id/11621/
Finalize Documents
70
Production Guide
Check
Compliance Info (UM/RM):
• Goes in the UM or RM when there is no UM.If the doc set has both a UM and an RM, put the compliance info into the UM only.
• Compliance info is present in the last appendix of the UM
• Compliance info includes this text right before the EDOC in languages of the European Community table:
For complete DoC please visit the NETGEAR EU Declarations of Conformity website at:?
http://support.netgear.com/app/answers/detail/a_id/11621/
• Compliance info is correct for the product. See
• Class variable is set correctly to Class A or Class B.
Product name is present in the compliance information:
• It’s handled with the Product Name (Long) variable in the new templates. Make sure your compliance information shows the product name and model number.
Waste Electrical and Electronic Equipment (WEEE) Notice with WEEE symbol. See
Add to IGs below the DoC paragraph:
For GNU General Public License (GPL) related information, please visit
http://support.netgear.com/app/answers/detail/a_id/2649
Make sure this text is on the IG:
Do not stack equipment, or place equipment in tight spaces, or in drawers. Be sure your equipment is surrounded by at least 2 inches of air space.
Prepare and Name Files for Agile Release
Table 2. Installation Guides
Check
Post the regular PDF file (named in the format WNA3100_IG_24MAY2010.pdf) and the zipped file only.
The zipped file is titled WNA3100_IGsrc_24MAY2010 and contains:
• The correct print specification.
• The Frame file.
• The Images directory.
• The print PDF (named in the format WNA3100_IGptr_24MAY2010.pdf).
• A MIF file in case the printer or anyone else encounters the FrameMaker bug that prevents opening the file.
Note:
For SMB projects, the organization is the opposite. The print PDF goes outside the zip file and the regular PDF goes inside.
Finalize Documents
71
Production Guide
Table 3. Manuals
Check
Post the regular PDF file (named in the format WNA3100_UM_24MAY2010.pdf) and the zipped file only. (The example is UM; substitute SM if it is a setup manual.)
The zipped file contains one directory called FmSrc. This directory contains:
• All the Frame source files
• The Vardefs.fm file
• The /Images directory
Accessibility Checks
If you are using the new template, setting the metadata with the Netgearutils > Set Metadata for book command, including the language option, introducing your figures right before they appear and/or using meaningful figure captions, your PDF is compliant with Section 508 of the Americans with Disabilities Act.
Adobe Acrobat provides several ways to check that your PDF is compliant, and these are
on page 95. You are not required to perform these checks at
this time.
Finalize Documents
72
Production Guide
Editing Guidelines
This section provides guidelines for which documents to edit and when to have them edited.
All installation guides for Home and Service Provider (SP) retail products should receive an edit every time they are updated. Other documents can be edited or not depending on whether they have been edited before, how much they have changed, how long they are,
schedule constraints, and editing priority (see
Also, some books might be important to develop as a base for future products. These could get more developmental editing usually from peers, but our editor should have a look at it as well.
Take into consideration the time involved to edit a long document that has not changed much since the last edit, and the time it will take you to update the document with the edits. These are guidelines and you should use your judgment to determine whether or not a document that is not an installation guide needs editing. Under no circumstances should the editing cycle cause a release to slip.
Note:
In general, do not have certification docs edited.
Editing Priority
1.
IGs: Home and SP-Retail
2.
IGs for other products.
3.
User/reference/CLI and setup manuals
Note:
GUI text and online help are edited as a high priority on the request of the product engineer.
Writers, if you notice errors in the GUI, please inform the engineer. If there are numerous errors and you have been asked to get screen shots, you might wonder what to do. It’s possible you are starting too early before the GUI is frozen. Also, find out if it’s a certification document before investing a lot of time in getting screen shots. See
on page 24 for guidelines on preparing certification documents.
Finalize Documents
73
Production Guide
Lead Writer’s Checklist
Lead writers use this checklist to ensure that a document is ready for Agile.
What
Part numbers
• Requested from Agile analyst at beginning of project
• Added to docs
Final files copied to Agile Drop Folder: V:\Operations\Document Control\AgileDropFolder\<<Model#>>
Notification email sent that files are in the Agile drop folder:
• Agile analyst
• Hsiang Lin (localization)
• Alice Ko (localization)
• Project engineer
• Tech support engineer(s)
• Suresh Venkatesan (Web)
• Naveen Swaroop Polavarum (Web)
• Technical publications manager
Final files copied to Current Projects: V:\Current Projects\<<Model#>>
Link and Web page on docs.netgear.com in this format: http://docs.netgear.com/modelnumber/language/partnumber/index.html http://docs.netgear.com/modelnumber/language/partnumber/index.htm
• Get page template from
http://docs.netgear/com/1sample-page
• See
• Example:
http://docs.netgear.com/cwge111/enu/202-10634-01/index.html
Finalize Documents
74
Production Guide
File Naming
Reference manuals, and other online documents are provided to the customer in a standard
PDF format. For print documents (except booklets), you have to make two PDF files. One standard PDF is for online viewing, and the second PDF is for the printing company. For booklets, you have to make three PDF files: A separate cover and interior PDF for the printer, and a combined PDF (cover first followed by the interior) for online viewing and for localization.
For custom layouts, new printing instructions must be written and approved. See
on page 99 for additional information about PDF preparations.
Sample File Names for QIGs
Follow these conventions to name the final PDFs:
•
WGXB102_IG_20Mar10 for the standard format PDF.
•
WGXB102_IGptr_20Mar10 for the press quality PDF that has registration marks.
Usually translation services handle foreign language versions, but occasionally Tech Pubs will format a document and create the PDFs. For foreign language versions, such as
German:
•
WGXB102_IG_GR_20Mar10
•
WGXB102_IGptr_GR_20Mar10 (for the print quality PDF)
For the Zip file archive name, use: WGXB102_IGsrc_GR_20Mar10.zip.
Sample File Names for Manuals
Follow these conventions to name the final PDF:
•
WGXB102_RM_20Mar10 for reference manuals.
•
WGXB102_UM_20Mar10 for user manuals.
•
WGXB102_SM_20Mar10 for setup manuals.
•
Use the same convention for CLI and hardware installation guides.
For foreign language versions, such as German:
•
WGXB102_RM_GR_20Mar10
•
For the Zip file archive name, use: WGXB102_RMsrc_GR_20Mar10.zip
For managed switch manuals:
•
7000_series_SM_8.0.3_22Jun10 for software setup manuals.
•
7000_series_SWA_8.0.3_22Jun10 for administration guides.
Finalize Documents
75
Production Guide
Sample File Names for Booklets
MCA1001v2_IG_interior_ptr_10Apr12
MCA1001v2_IG_cover_ptr_10Apr12
MCA1001v2_IG_cover+interior_10Apr12
Archive Documents
The PDF and a zip of the source files are archived. Source files use a directory structure of
/FmSrc/Images/ImgSrc. If additional source documents need to be preserved, such as Skype translation guidelines, place them in an /FmSrc/DocSrc folder. To archive, you need a program such as Winzip.

To create a Zip archive:
1.
Remove unneeded image files with the Move Unused Graphics command, described in the
2.
Delete the Reports, Images_Unused, and Images_Collected directories under FmSrc if they exist. These directories are created when you run FrameMaker tools, described in the
Chapter 8, Custom Tools Reference
.
Note:
If you have a one-file document, and you created a book file so you could run the FrameMaker tools, delete that book file.
3.
Put a copy of the PDF under the FmSrc directory.
4.
Zip the FrameMaker and image files (keeping the directory structure FmSrc/Image/ImgSrc).
5.
If the document is going to the printer, add the printer (ptr) PDF and print spec to the Zip file.
6.
Rename the Zip file based on the archive file-naming guidelines.
7.
Keep a copy of the regular PDF outside the zip file.
8.
Submit the Zip file and regular PDF for archiving.
Note:
For the SMB business unit, the printer (ptr) PDF is kept outside the zip file and the regular PDF is put inside the zip file.
Finalize Documents
76
Production Guide
Final Hand-Off from Offsite Writers

To hand off the file archive and final PDF.
1.
The offsite writer delivers the file archive and final PDF to the lead writer or the technical publications manager, using the geardog FTP site in the 4AgileRelease folder for final documents or 4Backup for WIP documents.
2.
The offsite writer notifies the lead writer or the Tech Pubs Manager that the files are ready and tells where they are.
3.
The lead writer or the technical publications manager places the file archive on the
NETGEAR V drive and notifies the applicable stakeholders as described in
Completed Projects That Do Not Go into Agile
Sometimes a platform is developed before there are customers, or a project goes on hold. In this case the documentation is not released into Agile. It would be stored in 4Backup on geardog and/or in Current Projects on the V drive instead.
Agile Pickup
The lead writer places the Zip and PDF files in the Agile drop folder and in current projects.
Agile Drop Folder
V:\Operations\Document Control\AgileDropFolder\<Model
Number>\Documentation\<document type>
For example:
V:\Operations\Document Control\AgileDropFolder\DGN2200\Documentation\UM
Current Projects
V:\Current Projects\<Model Number>\Documentation\<document type>
For example:
V:\Current Projects\DGN2200\Documentation\UM
Finalize Documents
77
Production Guide
Notification - All products Except Storage

The lead writer for the business unit logs in to TrackIt HelpDesk and creates a ticket:
To create a help ticket:
1.
Open a browser and go to the TrackIt page:
http://trackit.netgear.com/TIWEB8/scripts/TIWebPortal/TrackItUser.asp
2.
Click Manage your Work Order Requests.
3.
Click Add a new Work Order.
4.
Fill in the fields:
Priority: Normal.
Type: Document Control.
Subtype: File Archive.
Category: Select the Agile analyst for the product line.
Notes: Indicate which files are to be picked up and where they are.
5.
Click Submit.
6.
Send follow-up email to the Agile analyst, localization (Hsiang Lin and Alice Ko), project engineer, web master (Suresh Venkatesan), and the technical publications manager.
Notification - Storage Products
Write an email message addressed to the PLM and cc the analyst. Also include in the cc list anyone else who needs notification such as localization, engineering, support, and web, but
not Help Desk. The email message has the following information:
1.
Statement that the lead placed documentation for a project/product in an Agile drop folder, including the path.
2.
Reason for the documentation, as follows:
•
01 part number docs. The new product or products that the doc supports.
•
02 and higher part number docs. The product or products that the doc supports and the reason for the revision.
3.
Explicit request to the PLM to create a Help Desk ticket to update Agile.
When the Agile team finalizes the upcoming procedure change, the lead is required to approve the resulting ECO. The lead approval indicates that the correct files were included in the ECO.
Finalize Documents
78
Production Guide
CD Document Delivery
Some products ship with a CD. In those cases, the CD contains installation and setup software, and documentation. The information provided here is for informational purposes only. The writing team no longer manages the CD build process.
All matters related to CDs are handled by the CD Build engineer that is based in Taiwan. The position reports into the localization team.
Part Numbers
There are 4 P/Ns for a CD:
Format
103-xxxxx-0x CD (assembly)
1240-xxxxx-0x CD and label (subassembly)
230-xxxxx-0x Bits (ISO file)
270-xxxxx-0x CD label (.ai and.pdf file)
Example
103-10405-02 CD ASSY, SW,7000, V8.0.3
240-10596-02 SW,CD,ASSY,70000,V8.0.3
SW,CD,7000,V8.0.3
LBL,CD,7000,V8.0.3
Labels
A Word version of this information, the STD, CD, and DVD Manufacturing document
(DOC-00140) and CD label templates are available in V:\Current Projects\CD Labels
The CD label art is created in Adobe Illustrator (.ai). The small-medium business line uses several CD label templates.
•
ProSafe
•
ProSecure
•
NETGEAR (standard and wireless)

To create a CD label:
1.
Open a label template file (NETGEAR, ProSafe, or ProSecure using Adobe Illustrator.
2.
Make changes to the label specified by the engineer.
3.
Save and .zip the edited .ai file, using <model>_CDlabel_<date>.zip as the file name.
-
Include the standard label font file set in the .zip.
-
Example: 7000_CDlabel_28Jul09.zip.
4.
Create a PDF file for engineering review. Use the same file name format as above.
5.
Include your name as the author in the Properties list of the PDF.
Finalize Documents
79
Production Guide
6.
When approved, submit the .pdf and .zip files to Agile as the 270-xxxxx-xx files.
ï€
Templates
Figure 10. ProSafe CD template
Finalize Documents
80
Production Guide
Figure 11. ProSecure CD template
Figure 12. NETGEAR® CD template
Finalize Documents
81
7.
PDF Procedures
Make PDFs web-friendly and accessible
7
This chapter provides detailed information about preparing PDFs for release. Where applicable, troubleshooting information is included to resolve errors that might be raised during accessibility or preflight checks within Acrobat Pro.
The following topics are covered in this chapter:
•
Optimize PDFs for Search Engines
•
•
Prepare for Color or BW Printing (Preflight)
•
•
•
Link from within a PDF to External PDFs
•
•
•
See also
Add a Bar Code Directly to the PDF
82
Production Guide
Optimize PDFs for Search Engines
It is important to provide metadata for your PDF documents so search engines can find them and display intelligible results. You can provide the metadata either in Frame or directly on the PDF. It is better to add it in Frame so that it is applied to the PDF every time you generate the PDF from Frame. However, if you have a PDF and no Frame or other source files, you have to add the metadata to the PDF.
Set Metadata within Frame
The best place to get metadata into your PDF is in the Frame file at the book level. This way every time you generate the PDF, the metadata ports to the PDF. Read about it here:
http://help.adobe.com/en_US/FrameMaker/9.0/Using/WSACD8CF0D-726F-4bfd-8839-20E5
8074D5B1.html
To add metadata within Frame, use the Set PDF Metadata for Book command, described in
Add Metadata to the PDF
While it is better to add metadata to the source files, if you are in a situation where you have a PDF going on the Web and no source files, you can add the metadata to the PDF itself using Acrobat Professional.

To add metadata to the PDF:
1.
Open the PDF in Acrobat Professional.
Windows only. You can also enter and read the data properties information from the desktop. Right-click the document in Windows Explorer, select Properties, and click the
PDF tab. Any information you type or edit in this dialog box also appears in the Document
Properties description when you open the file.
2.
Select File > Properties.
3.
On the Description tab, provide the following information:
Title: As it appears on the front cover.
Author:
NETGEAR.
Subject: Use the title and/or write something appropriate.
Keywords: Use the title and/or add the appropriate keywords.
4.
Click Additional Metadata and provide the following information:
Copyright Status: Copyrighted.
Copyright Notice: Put in the year.
5.
Click Ok to save the additional metadata and click OK again to save properties.
PDF Procedures
83
Production Guide
Other Search Engine Optimization Tips
Search Engine Optimization Tips For PDF’s
ï€ by Nick Stamoulis
http://www.searchengineoptimizationjournal.com/2008/07/26/optimization-tips-2/
Many website owners release PDF versions of their content or ebooks in PDF format. For many commercial and professional websites, articles such as operating instructions are also written in PDF format. Your website may benefit if your PDF files are indexed and returned in search results for certain queries. However, search engine optimization for PDF format files can be slightly different to that of a normal web page.
I say slightly different because the general optimization concepts are still the same, it’s how you achieve those concepts that can make a big difference. The following tips may help to get your PDF indexed by the search engines.
Format. PDF’s can be produced in either a text or graphic format. Search engines cannot read the content of a graphic file so for SEO benefits; publish your PDF in text format.
META Tags. PDF’s don’t come with meta tag information. PDF’s do have a specific section where you can include a title, author, subject and keyword. Ensure this is filled in with relevant data. As with all web content, the title should be keyword optimized. This information is accessed through the document properties section.
Description. There is nowhere within a PDF to place a description. The description is the text that is returned in the search results. Left alone, the search engines will find the first paragraph of text and use that. This may not be a great ‘selling’ point to attract the searchers click. When you have completed your PDF you can specify the ‘reading order’. Place suitable text close to the front of the document and specify this to be read first.
Tags. If you use Acrobat to create your PDF then you can also specify tags including alt tags for images. This can be accessed in Acrobat through the TouchUp Reader Order panel.
Links. PDF files can and should have links. Links should use standard good white hat techniques such as anchor text. Since PDF’s can change hands several times, links within a
PDF back to your own pages can help bring extra traffic.
Version Control. By version control I am not referring to the PDF’s version, rather PDF reader versions. Don’t be too hasty to jump onto the latest version of Acrobat. Using an older version will ensure that search engines can ‘read’ your PDF. Search engines can be slow on the uptake when it comes to new versions.
Fast View. Fast View is an Acrobat option that allows the PDF to be loaded page by page rather than waiting for the entire file to be downloaded before opening. Fast View delivers the document to you reader quickly. Whilst not a true search engine optimization technique, if it loads too slowly and the reader hits the back button too soon, it can harm your search rankings.
Size. Along with Fast View, size does matter. Keep your PDF file to a reasonable size. For search engines, if the file is too large and takes to long to load, they will abandon it and not index it all.
PDF Procedures
84
Production Guide
Content. Finally we come to content. Treat your content like you would any other page. It should be keyword optimized without being keyword spammed.
PDF’s were once very popular however there seems to be an increase in the use of PDF’s again, particularly through ebooks. Your on page processes should treat the PDF like any other link. Link to it using relevant anchor text. Keep the PDF stored close to the root directory and available for indexing.
Creating a PDF file takes a lot of work. If you want to be able to have it indexed by the search engines then you should take that extra five minutes to ensure the effective search engine optimization strategies should be applied to it.
Create a PDF
Use FrameMaker 9.0 or later and Adobe Acrobat 9.0 Professional or later.
Acrobat Distiller
Remember to open Acrobat Distiller and check the Default Settings field before creating a
PDF from a .ps file. Otherwise Distiller uses whatever the settings were when you last distilled a project. This has a negative effect when you go from creating standard PDF to print quality PDFs. If you do not change your Distiller settings, then only the .ps file is created using print quality—the PDF is distilled at standard quality.
PDFs for Online Documents
You can use the Print Book or Save as PDF command to create a PDF from FrameMaker for an online document. Remember to run the Set PDF Metadata for Book command, described
on page 114to establish your PDF settings.

To use the Save as PDF Command:
1.
In the book file, select the book.
2.
Go to Format > Document > PDF Setup. In the PDF Setup dialog box, you should see:
Settings Tab
ï€
PDF Job Options. Standard
ï€
Open PDF Document on page. 1
ï€ at Zoom. FitPage
ï€
Registration Marks. None
ï€
Page Size. 8.5” x 11.0”
ï€
Page Range. All
ï€
Convert CMYK Colors to RGB. Selected
Bookmarks Tab
ï€
Bookmarks expanded through level. None
3.
Select File > Save as PDF.
4.
Click Set.
PDF Procedures
85
Production Guide

To use the Print Book Command
1.
In FrameMaker, select File > Print Book.
1.
In the Print Book dialog box, Printer section, click Setup.
2.
In the Printer Setup dialog box, Name drop-down list, select Adobe PDF, and then click OK.
3.
Click the Properties button, and make sure that the settings are correct on the Adobe PDF
Settings tab:
•
Default Settings: Standard; Adobe PDF Security: None. All check boxes should be selected except for the last one.
•
If you click Edit next Standard, the Resolution should be set to 600 dpi.
4.
Click PDF Setup. On the Settings tab, set the PDF Job Options to Standard, and the Page
Size to 8.5 x 11”. Check the Tags and Links tabs. The check boxes on these tabs should be cleared. (The check box on the Bookmarks tab should be selected).
5.
In the Print Book dialog box, click Browse and specify the location and file name for the
Postscript file.
6.
In the Print Book dialog box, click Print.
FrameMaker displays Printing Book:fullmanual.book while creating a Postscript file.
7.
Exit FrameMaker and click the Postscript file to launch Distiller and create the PDF file.
PDFs for Quick Install Guides (QIGs)
Quick install guides are printed documents. For review PDFs, make a standard-quality PDF that is the finished trim size of 17 x 7.25 without registration marks.
For final PDFs, you have to make two PDF files and include the print spec with the file set.
The print spec is located in same folder as the template within the 4TechPubs folder on the
FTP site.
•
Make a standard quality PDF with a finished size of 17 x 7.25 without registration marks.
•
Create a press quality PDF that is oversize by one inch (18.5 x 8.5) with Western registration marks.
PDF Procedures
86
Production Guide
Prepare for Color or BW Printing (Preflight)
Adobe Acrobat Professional has the Preflight command so you can verify that your PDF contains only the features, fonts, and formatting that you’ve specified. When you use this command, Acrobat inspects and corrects the document’s contents whenever possible, and issues errors and warnings for conditions that can be addressed only by the author.
Note:
Run Preflight on all documents that will be professionally printed and placed inside the box.

To analyze a PDF for color printing:
1.
Open the press quality PDF with the Western registration marks.
2.
Select Advanced > Print Production > Preflight.
3.
Select Digital Printing (color) to optimize the current PDF document for digital printing in color. Acrobat converts all colors including spot colors to CMYK.
The wrench icon indicates that this option includes fix-up.
4.
Click Analyze and fix. Save the file if prompted.
Note:
Run this command a second time if you get the Unable to save file after post processing error.
5.
Results appear in the Preflight dialog box.
Errors that Preflight was unable to fix are flagged with a red .

Cautions are flagged by a black exclamation point within a yellow triangle .
To analyze a PDF for black and white printing:
1.
Open the press quality PDF with the Western registration marks.
2.
Select Advanced > Print Production > Preflight.
3.
Select Digital Printing (B/W) to optimize the current PDF document for digital printing in black and white. Acrobat converts all colors including spot colors to black and white.
The wrench icon indicates that this option includes fix-up.
4.
Click Analyze and fix. Save the file if prompted.
Note:
Run this command a second time if you get the Unable to save file after post processing error.
PDF Procedures
87
Production Guide
5.
Results appear in the Preflight dialog box.
Errors that Preflight was unable to fix are flagged with a red .
Cautions are flagged by a black exclamation point within a yellow triangle .
Font Error
Font not embedded -- Fonts should always be embedded for prepress files. Fonts must be embedded for PDF/X-1 and PDF/X-3 files.
This means the listed fonts are not embedded in the PDF file. Embedding prevents font substitution when readers view or print the file, and ensures that the reader sees the original fonts. If you get this error, do one or more of the following as needed:

To troubleshoot font errors:
1.
Check that you ran Preflight on the press quality PDF.
2.
Start Distiller, go to Settings > Edit Adobe PDF Settings, choose Fonts in the left column, and make sure Embed all fonts (at the top) is selected for the Press Quality job option. If it is not selected, you might be prompted to create another job option such as Press Quality
(1).
3.
In the Embedding section, make sure the fonts causing the error are not listed in the Never
Embed list.
PDF Procedures
88
Production Guide
With Embed all fonts selected, all fonts listed in the left window under Embedding are embedded except fonts listed in Never Embed. If a font has been moved from the left list to Never Embed, you have to then move it to Always Embed if you want it embedded.
4.
Select ~Program Files > Adobe > Acrobat 9.0 > Acrobat\Settings, and use a text editor to add the following PostScript setting to the Press Quality job options file: /EmbedAllFonts true.
Note:
Ideally, you should embed fonts for all job options you use to generate PDFs to prevent font substitution in all PDFs.
A font can be embedded only if it has a setting provided by the font vendor that permits it to be embedded. When a font cannot be embedded because of the font vendor’s settings, and someone who opens or prints the PDF does not have access to the original font, a Multiple
Master typeface is temporarily substituted: AdobeSerifMM for a missing serif font and
AdobeSansMM for a missing sans serif font.
The Multiple Master typeface can stretch or condense to fit to ensure that line and page breaks in the original document are maintained. The substitution cannot always match the shape of the original characters, however, especially if the characters are unconventional ones, such as script typefaces.
PDF/X is an umbrella term for several ISO standards that define a subset of the PDF standard. PDF/X facilitates graphics exchange and so has a series of printing-related requirements that do not apply to standard PDF files. Read more here:
http://en.wikipedia.org/wiki/PDF/X
Compressed Object Streams Warning
Compressed object streams used (except for tags) warning.
A PDF file consists primarily of objects that contain data such as Boolean values, numbers, strings, names, arrays, collections, streams, and empty objects. An object can be either embedded in another object (direct) or indirect. Object streams were introduced in PDF 1.5
(Acrobat 6.0) as a mechanism where indirect objects can be located in special streams called object streams. This technique reduces the size of files that have large numbers of small indirect objects and is especially useful for reducing the size of Tagged PDFs.
This warning is to alert you that the PDF contains object streams because it was created with
Acrobat Professional 6.0 or later, and if it is not read with Acrobat Reader 6.0 or later, the user might experience performance and/or reliability degradation.
Other than recommending that the reader use the freely available Acrobat Reader 6.0 or later, there really is not anything else to do about this warning. It’s quite possible that if the reader experiences difficulties, he or she would upgrade Acrobat Reader on their own.
PDF Procedures
89
Production Guide
Crop Marks on PDFs
It’s best to add crop marks within Frame, but if you have a PDF and no source files, follow these instructions to enlarge the page and add the crop marks to the PDF.

To enlarge a PDF to Allow for Crop Marks

1.
Open the PDF file in Acrobat.
2.
Select Document > Crop Pages.
3.
Click Custom.
4.
Enter custom size (at least 1 inch larger width and height than the trim size of the document to allow for crop marks.
5.
The Center check box should be checked.
6.
Click OK.
To add Crop Marks to a PDF
1.
Open the PDF in Acrobat
2.
Select Advanced > Print Production > Add Printer Marks
3.
Click OK
Combine PDFs

To combine PDFs:
1.
Open the PDF in Acrobat
2.
Select File > Combine > Merge Files into a Single PDF. A window lists the first PDF.
3.
Drag and Drop the remaining PDF files into the list.
4.
Order the PDFs (right-click a file name and select Move Up or Down).
5.
Click Combine Files.
6.
Save the combined file to a new name.
Link from within a PDF to External PDFs
You can link to external PDFs from within a source PDF. It is best to do this on a final PDF because you have to redo the links every time you create a new source PDF. This can be useful if you have a Word file with embedded PDFs. When you make a PDF from the Word file, that source PDF has the Adobe PDF icons, but those icons are inactive. You can use tools within Acrobat Professional to put a transparent button over the icon and define the button to open a specific external PDF file.

To link to an external PDF:
1.
Create a PDF from the Word file.
PDF Procedures
90
Production Guide
2.
Open the PDF and page through and find an Adobe PDF icon.
3.
Select Forms > Add or Edit Fields. You don’t want Adobe to detect form fields for you.
4.
At the top left below the PDF menus, select Button from the Add New Field drop-down list.
5.
Use your pointer to position the button over the Adobe PDF icon.
6.
Click Show All Properties. Alternately, you can double-click the button.
7.
In the General tab of the Show All Properties dialog box, type Click me in the Tooltip field.
This will make the text Click me display when the user hovers over the Adobe PDF icon.
8.
In the Appearance tab, set the fill color to No Color.
9.
In the Actions tab in the Select Action drop-down list, select Open a File and click Add.
10.
In the Select File to Open dialog box, select the file you want the button to open.
11.
In the Specify Open Preference dialog box, select New Window and click OK.
12.
Close the Button Properties dialog.
13.
To test the button, select Forms > Close Form Editing.
14.
Click the Adobe PDF icon to open the reference file.
15.
Find the next Adobe PDF icon and repeat the previous steps.
Add A Watermark

When you add watermarks to a PDF document, you want them to be visible and unobtrusive.
To add a watermark:
1.
Inside Acrobat Professional, select Document > Watermark > Add
2.
In the Add Watermark dialog box, provide the following settings:
Font: Arial
ï€
Size: Varies. For shorter watermarks like the word Draft, 72 pt works well.
ï€
Color: Pure red (R: 255, G: 0, B:0)
ï€
Rotation: 45°
ï€
Opacity: One notch above zero on the slider (12%)
ï€
Location: Appear on top of page
3.
Optional. To apply the water mark to a specific range of pages, click select Page range
options in the upper-right corner of the Add Watermark window.
PDF Procedures
91
Production Guide
PDF Procedures
92
Production Guide
Tagged PDFs
One function of tagged PDFs is to make a document accessible to the visually impaired.
Visually impaired individuals can surf the Web and read PDFs using screen-reading software that offers audio cues to help them navigate. The main barrier to accessibility is that PDF documents are not always designed by their authors to be compatible with screen readers.
Adobe has developed a number of tools and resources to make it easier for authors to create accessible PDF documents; these are available at
http://www.adobe.com/accessibility
.
Characteristics of a correctly tagged PDF:
•
A logical structure and reading order.
•
Alternate text descriptions for page elements displayed not as text, but visually, such as figures and form fields.
Note:
We introduce figures in the text right before the figure rather than include alternate text for each figure.
•
Navigational aids such as links, bookmarks, table of contents, and index.
•
Security that doesn’t interfere with assistive technology. Restrictions that interfere with printing, copying, extracting, commenting, or editing text can interfere with a screen reader’s ability to convert the on screen text to speech.
•
Fonts that allow characters to be extracted to text. If a font’s underlying information is sufficient, each character can be extracted for the screen reader, printing, copying, pasting, or saving to a text file. If the information is not sufficient, characters and words might be omitted or you might see question marks, black rectangles, or other marks when you print, copy, paste, or save the PDF to text.
Section 508 of the Americans with Disabilities Act
Firms that do business with the government or (potentially) work for clients, who have government contracts, are required to create documents that are accessible to the visually impaired. Section 508 is the law that applies. The NETGEAR service provider product line
does business with third-party service providers. It is likely all or some of those third parties do business with the government .
In 1998, Congress amended the Rehabilitation Act to require federal agencies to make their electronic and information technology accessible to people with disabilities. Inaccessible technology interferes with an individual’s ability to obtain and use information quickly and easily. Section 508 was enacted to eliminate barriers in information technology, to make available new opportunities for people with disabilities, and to encourage development of technologies that will help achieve these goals. The law applies to all federal agencies when they develop, procure, maintain, or use electronic and information technology. Under Section
508 (29 U.S.C. 794d), agencies must give disabled employees and members of the public access to information that is comparable to the access available to others.
PDF Procedures
93
Production Guide
Structure
Tagged PDFs have a logical document structure (organization) and extensive metadata for repurposing content. Tagged Adobe PDF provides the following capabilities:
•
Ensures that information is in the correct reading order on a page.
•
Includes paragraph attributes used to correctly reflow the document contents into different-sized devices, such as eBook reading devices.
•
Ensures the reliable translation of text into Unicode. This approach recognizes ligatures and hyphens so a Windows screen reader can correctly read all characters and words.
•
Recognizes alternative text descriptions for graphics in anchored frames.
•
Enables the document to be exported more reliably to Rich Text Format (RTF) and XML from Acrobat 7.0 for reuse in other documents.
Tagged PDFs have author content (pages, articles, paragraphs, tables, and graphics in anchored frames), but do not have the following information found in standard PDFs:
•
Comments, such as online notes, graphic markups, and text markups.
•
Pagination artifacts, including all content that comes from master pages (such as page numbers and running headers), and any graphic objects outside anchored frames.
•
Layout and typographic artifacts, such as colored bars between columns of text, horizontal lines separating footnotes from text, and table borders.
•
Printing artifacts, such as crop marks, registration marks, and page information printed outside the crop marks.
Generate a Tagged PDF
Generating a tagged PDF from FrameMaker involves specifying bookmarks, the default book structure, and setting the language. Acrobat Professional provides accessibility checks to verify that the tagged PDF has no errors. The checks and errors are described in
Specify PDF Settings
The PDF settings are for bookmarks and the default book structure. The easiest way to set
these is to run the Set PDF Metadata for Book command, described in
on page 114. This command also sets the book metadata for search optimization.
Set the Language
You can set the language in FrameMaker or directly on the PDF.
Within FrameMaker
This is done once per book. You place a text box with a pdfmark (a PostScript extension) on the first page of the first chapter in a FrameMaker book file.
PDF Procedures
94
Production Guide
The new templates have this text box in place on the first page of the frontmatter.fm file. The pdfmark is white so the text does not show up. You see only the outline of the text box above
“NETGEAR.” Copy the text box from the fontmatter.fm template file into the same location in your bookfrontmatter.fm file and you are all set. This will work whether your book is using the new template or the old one.

To add the text box with the pdfmark manually:
1.
Open the first file in the book.
2.
In the first body page of the file, add a text frame outside the main flow of the document.
3.
Put the following text in the text frame:
ï€
[{Catalog}<< /Lang (en-US) >> /PUT pdfmark
Note:
Here, the language is specified to be en-US (US-English). It can be any ISO string such as, es-MX (Mexican Spanish), fr-CN (French
Canadian), and so on.

4.
Select the text frame and bring up Object Properties. Turn on Postscript Code.
5.
Make the text white so it does not show in your document.
6.
Save and close the file.
7.
Export the book to PDF.
8.
In the PDF, select File > Properties and click the Advanced Tab.
9.
Check the reading options where it should say Language: English.
To put the text book with the pdfmark directly in the PDF
This has to be done every time you generate the PDF.
1.
Open the PDF.
2.
Select File > Properties.
3.
On the Advanced tab under Reading Options, set the language to English.
4.
Click OK.
Test a Tagged PDF
Acrobat provides three ways to test a PDF for accessibility compliance and they are described here in their recommended order.
Read Out Loud
The Read Out Loud feature reads aloud the text in a PDF, including the text in comments and alternate text descriptions for images and writable fields. In tagged PDFs, content is read in the order in which it appears in the document’s logical structure tree. In untagged documents, the reading order is inferred, unless a reading order has been specified in the Reading preferences. This is the minimum test a PDF must pass to meet accessibility requirements.
PDF Procedures
95
Production Guide

To use the Read Out Loud feature:
1.
Open your tagged PDF in Acrobat.
2.
Select View > Read Out Loud > Activate Read Out Loud.
3.
Select View > Read Out Loud > Read To End of Document.
You can leave the document running and come back and check it in a few hours. If the reading makes it to the end of the document, the PDF has met the minimum requirement for accessibility compliance. If the file stops, there is probably a font-tagging issue. See
on page 98 for ways to locate and fix the problem.
You might want to spot check pages for the following things:
a. Listen for figure numbers, figure captions (if used), and alt text (if used). If these are not read, the most likely cause is a problem with the anchored frame. It might contain more than one object, for example.
b. If you hear headers and footers being read, the most likely cause is that the structure is wrong due to a tagging problem.
Run Full Check
Use Full Check to check a PDF for many of the characteristics of accessible PDFs. While this is not required to meet minimum accessibility requirements, it is a good idea to run this test and fix as many errors as possible to make your PDF more accessible to different types of accessibility equipment.

To run a full accessibility check:
1.
Open your tagged PDF in Acrobat.
2.
Select Advanced > Accessibility > Full Check.
3.
Clear the Alternative descriptions are provided, All form fields have descriptions, and
Tab order is consistent with the structure order check boxes. We are not including alternate text on figures at this time, and the other two options pertain to PDF forms and are not relevant to our documents.
4.
Accept the rest of the defaults. If you want problem areas flagged with comments within the document, select the Create comments in document check box, which is cleared by default.
5.
Click Start Checking.
A report appears in the left column of reader with instructions on how to fix problems on the PDF. It’s best to fix the problems in the Frame source if possible.
Reflow Document
You can reflow a PDF to temporarily present it as a single column that is the width of the document pane. This reflow view can make the document easier to read on a mobile device or magnified on a standard monitor, without the need to scroll horizontally to read the text.
If your PDF reads out loud all the way through and the Full Check test shows no elements
outside the structure tree (see
on page 97, the reflowed document
PDF Procedures
96
Production Guide
should be in good shape. You do not need to perform this test to meet minimum accessibility requirements.

To reflow a document:
1.
Open your tagged PDF in Acrobat.
2.
Select View > Zoom > Reflow.
3.
Resize the PDF and watch the text flow. Spot check that all page elements are within the flow by looking for any odd presentations that seem incorrect. Note that you do not see graphics in reflow mode.
4.
To fix problems, run the Full Check test and correct the errors that come up. Pay particular attention to structural errors.
Error Messages and Fixes
These are common error messages generated by the Acrobat Full Check. It’s best to fix these in the Frame source, if possible. Some fix suggestions are provided here.
•
None of the images on this page that need alternate text have it.
This one means the figure has no alternate text. You can add the alternate text in Frame or in the PDF. For now, we are not adding alternate text to figures, so you will routinely see these errors when you run the Full Check unless you clear the Alternative
descriptions are provided check box before running the Full Check. See
on page 98 for easy instructions for adding alternate text.
•
All of the text on this page lacks a language specification.
The PDF needs it’s language specified. See
on how to do set the language specification.
•
This document is not tagged.
Run the Set PDF Metadata for Book command described, in
•
Tab order may be inconsistent with the structure order. This pertains to PDF forms. Check
that the Tab order is consistent with structure of the book as described in
The tab order refers to when the person reading the PDF uses the Tab key to navigate elements such as buttons and links on the page or on a PDF form. It is desirable for the person to reach the elements in a specified order, which might or might not follow the structure of the document. This error shows up in our documents on pages that have links. Accessibility readers follow the structure of the document by default.
•
xxx element(s) that are not contained within the structure tree.
When this error comes up for a generated table of contents or index, it usually happens on the first entry on the second and later pages. If the error comes from the index, you can investigate the following causes, but if they are not the source of the problem and the
Read Out Loud feature reads through the problem area, you have met the minimum accessibility requirements.
PDF Procedures
97
Production Guide
•
An index marker does not have a space after the colon in a hierarchical index entry.
•
Single index markers containing many multiple-level tags can give this error. One fix is to create several index markers instead of putting three or four into one marker.
In non-generated files, the following situations might be causing the problem. If you are unable to find and fix the problem and the Read Out Loud feature can read through where the problem is, you have met the minimum accessibility requirements.
•
Two fonts are applied to the same text.
•
An unknown element is present in the Frame source due to copying and pasting from another document type such as word, PDF, or HTML. Try retagging it.
Clean up Font Problems
Font problems are a common reason the Read Out Loud feature cannot complete reading.
These are some possible causes for font problems:
•
A font change is not tagged (a URL or copyright text has been screen copied and has introduced odd characters, or text has been pasted from a legacy Frame or other document.)_
•
A string has more than one font tag such as a URL tag and an emphasis tag.
To fix the problem, do a visual inspection and manually select each font change one by one.
Check the character designer on the Info bar at the bottom of the document window to confirm that the characters are correctly tagged. When you find untagged or incorrectly tagged text, first remove the invalid tag and, then apply the correct tag.

To delete an invalid tag:
1.
Select the untagged or correctly tagged text.
2.
In the font catalog, select Default Character Font.
3.
Select the correct font tag.
Add Alternate Text to Figures
FrameMaker 9 help explains how to add alternate text to figures.

To add alternate text to figures:
1.
All figures have to be inside an anchored frame.
2.
Select the anchored frame.
3.
Select Graphics > Object Properties.
4.
In the Object Properties dialog box, select Object Attributes.
5.
In the Object Attributes dialog box, provide the alternate text in the Alternate field.
6.
Click Set.
PDF Procedures
98
Production Guide
Send PDFs Out for Review
Use Adobe Acrobat 9.0 Professional or later to create a PDF email review. Markup tools are automatically sent with the PDF to the reviewers. If the reviewers email PDF markups back to you, Acrobat offers you the option to put all comments into a single markup PDF file.
For very large books, use the Send for Shared Review feature to specify the reviewers, upload the file to the Adobe web site (
http://acrobat.com
), and notify reviewers by email.
Note:
It can be helpful to turn off your email until after you have edited the boilerplate email message created by Acrobat.

To prepare and send a PDF out for review:
1.
Create the PDF.
2.
Open the PDF in Acrobat. For PDFs less than 5 MB in size, select Comment > Attach for
Email Review. For larger PDFs, select Comment > Send for Shared Review or
Comments > Enable for commenting and Analysis in Adobe Reader. For larger PDFs see the next section.
3.
Follow the wizard prompts. Acrobat creates an email message in your outbox with boilerplate content and the PDF attached.
4.
Add text to the boilerplate email message to specify the type of review (developmental, technical, or release approval) and the due date for replies.
5.
Send the email to the reviewers.
Make Large PDFs Available for Review
For very large books, use the Send for Shared Review feature to specify the reviewers, upload the file to the Adobe web site (
http://acrobat.com
), and notify reviewers by email.
To reduce large PDFs, there are two optional steps in Adobe Pro:
•
Advanced > PDF Optimizer
•
Document > Reduce File Size.
PDF Procedures
99
8.
Custom Tools Reference
Learn our custom FrameMaker tools
8
The custom NETGEAR tools for FrameMaker automate time-consuming tasks commonly done when converting documents from the old format to the new format, and when starting and finalizing documents. The custom menu, called NetgearUtils, appears on the FrameMaker book menu bar after you install the tools as described in
Appendix A, Install Custom Tools
This chapter explains the files, tools, and reports associated with the NetgearUtils menu:
•
•
•
•
•
•
•
•
•
Creating Useful Metadata (Optional)
•
•
•
Note:
These tools were made for the sole use of NETGEAR employees and contractors. The tools cannot be given to anyone else or to any other company.
100
Production Guide
NetgearTools Folder and Files
Appendix A, Install Custom Tools
, explains how to create a NetgearTools folder in the
FrameMaker 9 installation folder and add the tools files listed in
into that folder. These tools files are used by the NetgearUtils menu commands to
automate conversion tasks.
When a new release of these tools come out, copy the new files into the NetgearTools directory and restart FrameMaker. The table below explains the purpose of each file.
Table 4. NetgearUtils Files Usage
File
report.tpl
pdfsettings.fm
netgearutils.dll
remapper.dll
RemapConfigFile.fm
Description
Provides the output formats for the reports generated by the various report commands. These reports are saved to the book directory under a reports directory.
Contains the bookmarks and tagged PDF settings that are applied to the current book when the Set PDF Metadata for Book command runs. To view the settings, open pdfsettings.fm in Frame, select Format > Document > PDF
Setup and view the settings under Bookmarks and Tags.
This tool also reads certain book variables and references a pdfcode in the front matter file to set the PDF metadata (for improved search) and the language option to English (for accessibility compliance). See
Contains the executable tools code for all tools except the template tools.
Contains the executable template tools code.
Specifies the mapping of the old catalog tags to the new template catalog tags.
The conversion tool uses this file to remap tags and clean up catalogs. See
Custom Tools Reference
101
Production Guide
NetgearUtils Menu
This section covers tool behavior and contains a description the custom tools available on the
NetgearUtils menu. These tools help you manage FrameMaker books, convert older docs to the new format, and keep already converted docs up-to-date with the latest NETGEAR style.
Once installed as explained in
Appendix A, Install Custom Tools
function and is explained in detail in this document.
Figure 13. The NetgearUtils menu within FrameMaker
The following topics are covered within this section:
Custom Tools Reference
102
Production Guide
Commands and Book Files
Each NetgearUtils tool has a specific function and handles the book files differently depending on which command you are running. Some of the tools require that the book files be open and other tools require that the book files be closed.
•
Commands that run if the files are open or closed:
Reports (list), Move and Collect commands, and URL tools. It is not necessary to close the documents before executing report, move, and collect commands because these commands do not change anything in the documents.
•
Commands that require all files to be closed:
Edit and Set PDF Metadata on Book commands. When running edit commands or the
Set PDF Metadata on Book command, the tools require that all files be closed. This is because edit commands are programmed to save and close only changes made by the commands. If you have open files, the edit commands prompt you to close the files before proceeding.
•
Commands that open all files in the book:
Update Current Book to New Templates commands. All of these commands open all the files in the book.
One-File Documents
If you have a one-file document, such as an installation guide, and you want to use the tools, make a book for that file and make the final PDF from the book. When you archive the document, do not include the book file.
Note:
When you run the Set PDF Metadata on Book command, the metadata is added to the book. With one-file documents where the book is not saved with the file, you lose the metadata. To prevent this, add the metadata directly to the one file with the FrameMaker
File > File Info command.
Custom Tools Reference
103
Production Guide
Cross References Tool
The following commands are available under NetgearUtils > Cross References. These commands maintain consistently defined cross-references across all files of the book and update cross-references to point to the local files.
List of Cross-Ref Formats in Book
Edit Cross-Ref Formats in Book
Collect Outside Cross-References
List of Cross-Ref Formats in Book
This command generates a three-column table for each cross-reference defined in the book.
The following figure shows the cross-reference formats for the Appendix definition. Each table within the report lists from left to right: the File Name, the Cross-Reference Definition used in that file, and the pages where that definitions occurs, Occurs in Pages.

To list cross-reference formats:
1.
Select Cross-References > List of Cross-Ref Formats in Book.
2.
In the report, select the file name in the left column to open the file.
3.
Use FrameMaker’s Edit > Find/Change command to locate the cross-reference.
Link to File
Note:
Legacy content might include numerous versions of the same x-ref; for example, Heading & Page, Heading and Page, Heading_Page. If
you are unsure which is correct, refer to

To identify Cross-references Not Used in the Book
1.
Run the List of Cross-References Formats in Book report.
2.
Look at the third column Occurs In Pages for each cross-reference definition.
Custom Tools Reference
104
Production Guide
3.
If all rows in that table show <No Occurrences>, that means the cross-reference is not used anywhere in the book and can be deleted.
Edit Cross-Ref Formats in Book
This command brings up a dialog box that lets you edit the cross-reference formats across the entire book.

To display the dialog box:
Select Cross-References > Edit Cross-Reference Formats in Book.
The example shows that the BookTitle cross-reference is used in every book file and has a consistent definition across the files. The highlighted definition displays in the edit box where you can edit or delete that definition as described in the following procedures.
Figure 14. Cross-references editor columns, text box, and buttons
•
Name in Book. This column lists the cross-reference definition names for the entire book in alphabetical order.
•
Book Filename. This column lists all of the book files where the selected cross-reference exists in alphabetical order. Ideally this would be all files in the book, but is not always.
You might have a cross-reference that exists in only one or a few chapters.
•
Definitions. This column lists the cross-reference definition in each file where the cross-reference exists so you can scan for consistency.
•
Set Definition. This button lets you set a definition one-by-one until you have redefined all the cross-references you want to for the current session.
•
Delete Selected. This button lets you delete a cross-reference from the book.
•
Un-Delete Selected. This button lets you reverse a deletion. You have to reverse the deletion before you click Commit Changes into Book.
Custom Tools Reference
105
Production Guide

•
Commit Changes into Book. This button commits all of the changes you made with Set
Definition, minus any changes you undid with Un-Delete Selected.
•
Cancel. This button quits out of the session without making any changes.

To edit Cross-Reference Definitions
1.
In the Name in Book column, highlight the cross-reference you want to change.
2.
In the Definitions column, highlight the definition you want to change.
3.
In the Set definition box, make the change to the definition you want.
4.
Click Set Definition. All files now show the new definition.
5.
Repeat Steps 1-4 for every definition you want to change.
6.
Click Commit Changes into Book. All files are updated with the current definition regardless of whether the definition was changed in the session or not.
To delete a Cross-Reference
1.
Select NetgearUtils > Cross-References > List of Cross-Ref Formats in Book command to identify which formats are not being used and can be deleted.
2.
Select the cross-reference you want to delete in the Name in Book column.
3.
Click Delete Selected. The format moves to the top of the list and is marked with [Del].
4.
If needed, select another cross-reference and click Delete Selected.
5.
When you are done, review the formats selected for deletion and:
a. If you want to remove one from the list, select it and click Un-Delete Selected.
b. When everything looks fine, click Commit Changes to Book
Note:
When you select Commit Changes to Book, the command deletes the cross-references you have specified even if one or more of the cross-references is used in the book somewhere. A deleted cross-reference that is used in the book turns to text, which makes it hard to spot and fix.The command does not warn you before you
delete a cross-reference that is used in the book. See
Cross-references Not Used in the Book
Collect Outside Cross-References
This command traverses the list of cross-references in the book and determines whether the cross-reference is to a file in the local directory or not. For each cross-reference, if the cross-reference is somewhere outside of the book’s local files directory, it does the following:
1.
If a file exists with the same name in the book’s local files directory, the tool resolves the cross-reference to the file in the local directory by breaking the link to the outside file.
2.
If there is no file with the same name in the book’s local files directory, it copies the remote file into the local files directory and resets its link to point to the local file.
Custom Tools Reference
106
Production Guide
3.
Then it reports that a file was copied from location A to the local directory. The message is a link to the cross-reference in the document. Click the filename path to open the file where the cross-reference is if you want to review it.
Graphics Tool
The following commands are available under NetgearUtils > Variables. These commands maintain consistently defined cross-references across all of the files in the book.
•
•
•
List of Graphics in Book
This command generates a report of embedded graphics and graphics imported by reference.

To list graphics:
1.
Select Variables > List of Graphics in Book to generate the report.
2.
In the report, select the graphic file name in the left column to jump to the image. This also works for embedded images, which are listed in the List of Graphics in Book report as
CopiedImage. The word CopiedImage is a link to the actual image in the book. The report tells you that page 3 of Production Guidelines.fm has a copied image.
Link to image
Note:
If the image exists only on the disk and is not used in the book anywhere, the path is not a link.
In this next report, the Production Guidelines.fm file has seven graphics imported by reference. The table tells you the Graphic Name, the Graphic File Path where
FrameMaker is getting the graphic, and what page it is on in the file (On Page).
Custom Tools Reference
107
Production Guide
Link to image
Move Unused Graphics
The Move Unused Graphics command moves all graphics not used in the book to the
Images_unused directory. This includes graphics that are copied into the book. If you do not want these images moved, put them in a subdirectory called EmbeddedImages. When this command completes, a dialog box displays to tell you how many unused graphics it found and where they are.
Figure 15. Number of unused graphics moved
Note:
Embedded template images are in the Images and Icons directories of the template. There is no need to do anything with embedded template images.
The Move Unused Graphics command also generates the Move Unused Graphics report to tell you which graphics were moved from the images directory. The entries in the report are links to the image.
Custom Tools Reference
108
Production Guide
Figure 16. Move Unused Graphics report
Collect Outside Graphics
This command traverses the list of images that are imported by reference in the book. The command can read the images directory regardless of case: images, Images, IMAGES, and so on. For each referenced image, if the image is somewhere outside of the book’s Images directory, it does the following:
1.
If there is an image with the same name in the book’s local Images directory, it copies the image into Images_collected.
2.
If there is no Image with the same name in the book’s Images directory, it copies the image into the Images directory.
3.
It then updates the path in the FrameMaker source file to reference all images in the local
Images directory, alerts you there are images in images_collected to check, and generates a report telling you which graphics were collected for what file and from where.
If you have duplicate images in Images_collected, check to see if they are the same or different to determine which image you want to use.
The following report shows a partial section form the Collect Outside Graphics report. The top entry shows one image was collected from another directory and moved to the local directory for the FrameTools.fm file. The bottom entry shows no images were collected for the
Reviews.fm file. Click the filename path to open the file, and click image path to go the page in the file where the image is used.
Custom Tools Reference
109
.
Production Guide
Link to File
Link to Image
Figure 17. Collect Outside Graphics report
Variables Tool
The following commands are available under NetgearUtils > Variables. These commands eliminate the need to maintain a separate vardefs.fm file for every book. These commands help you have consistently defined variables across all files of the book.
List of Variable Definitions in Book
Edit Variable Definitions in Book
Custom Tools Reference
110
Production Guide
List of Variable Definitions in Book
.
This command generates a three-column report for each variable defined in the book. following report shows the definitions for the Product Family in line variable. Each table lists from left to right the File Name, the Variable Definition used in that file, and the pages where the definitions occur. Click on the file name in the left column, to open the file in FrameMaker so you can use the Edit > Find/Change command to locate the variable
Link to File
Figure 18. List of Variable Definitions in Book report

To identify variables not used in the book
1.
Run the Variables Definitions report
2.
Look at the third column Occurs In Pages for each variable definition
3.
If all rows in that table show <No Occurrences>, that means the variable is not used anywhere in the book.
Note:
Most of the variables not used in the book can be deleted, but you should not delete any of the standard variables even if you are not using all of them. The Book Title and Keywords standard variables are not used in the book but the Set PDF Metadata on Book
command uses them to generate metadata. See
on page 143 for a complete list of the standard variables.
Custom Tools Reference
111
Production Guide
Edit Variable Definitions in Book
This command lets you edit and delete variables and update the entire book with your new variable definitions. The figure shows that the BookTitle variable is used in every book file with the same definition except in the compliance appendix.
Figure 19. Variable editor columns, text box, and buttons
•
Name in Book. This column lists the variable definition names for the entire book in alphabetical order.
•
Book Filename. This column lists all of the book files where the selected variable exists in alphabetical order. Ideally this would be all files in the book, but is not necessarily the case. You might have a variable that exists in only one or a few chapters.
•
Definitions. This column lists the variable definition in each file where the variable exists so you can scan for consistency.
•
Set Definition. This button lets you set a definition one-by-one until you have redefined all the variables you want to for the current session.
•
Delete Selected. This button lets you delete a variable from the book.
•
Un-Delete Selected. This button lets you reverse a deletion. You have to reverse the deletion before you click Commit Changes into Book.
•
Commit Changes into Book. This button commits all of the changes you made with Set
Definition, minus any changes you undid with Un-Delete Selected.
•
Cancel. This button quits out of the session without making any changes.

To edit variable definitions
1.
In the Name in Book column, highlight the variable you want to change. In the above example, that would be the BookTitle variable.
2.
In the Definitions column, highlight the definition you want to change opposite the file in which you want to change it.
Custom Tools Reference
112
Production Guide

3.
In the Set definition box, make the change to the definition you want. In this example that would be, N150 Wireless ADSL2+ Modem Router DGN1000 User Manual.
4.
Click Set Definition.
5.
Repeat Steps 1-4 for every definition you want to change.
6.
Click Commit Changes into Book. All files update with the current definition regardless of whether the definition was changed in the session or not.
To add a new variable
Some product lines have special considerations. For example, a hardware installation guide
(HIW) could cover up to three switches. You could add and use three variables such as
Produce Model #1, Produce Model #2, and Product Model #3 instead of Product Model # in this situation.

1.
Add the variable to any file.
2.
Select NetgearUtils > Variables > Edit Variable Definitions in Book.
3.
Select the variable definition you just added in the Name in Book column.
4.
Click Set Definition.
5.
Click Commit Changes into Book.
To delete a variable
1.
Select the variable you want to delete in the Name in Book column.
2.
Click Delete Selected.
3.
If needed, select another variable and click Delete Selected.
4.
When you have selected all of the variables to delete, click Commit Changes to Book.
Note:
When you select Commit Changes to Book, the command deletes the variables you have specified even if one or more of the variables is used in the book somewhere. A deleted variable that is used in the book turns to text, which makes it hard to spot and fix. The command does not warn you before you delete a variable that is used in the book. See
To identify variables not used in the book
on page 111 for information on how to verify whether a variable is used
in the book or not.
Custom Tools Reference
113
Production Guide
Set PDF Metadata for Book
The Set PDF Metadata for Book command does two things and then saves the book
.
•
Reads the bookmark and tagged PDF settings from pdfsettings.fm in your NetgearTools directory and applies them to the book so that all books use consistent settings.
•
Reads the variable information for the variables listed below from the first file in the book.
It then populates the File > File Info box in FrameMaker with the data in the variables.
When you make a PDF, the File Info data populates the File > Properties fields of the
PDF. The Properties data is called metadata and is used by search engines to find and display PDF information in search results.

To set up variables for the metadata:
1.
Put the variables listed below in the first file in the book if they are not already there.
Spell the variable names exactly as shown using one or two words as indicated.
Variable
Company Name
Book Title
Product Name (long)
Keywords
Copyright
PDF Metadata
Author (NETGEAR, Inc.)
Title
Subject
Keywords
Copyright
Behavior
Empty if the variable not defined
Empty if the variable not defined
Empty if the variable not defined
Empty if the variable not defined
Empty if the variable not defined
2.
Define the variables to contain the metadata that you want to be exported to the PDF file.
You can use the example settings shown here or supply your own data. See
on page 115 below for hints on creating good metadata.
Author. NETGEAR
ï€
Book Title. As it appears on the front cover
ï€
Subject. Use the book title and/or write something appropriate
ï€
Keywords. Use the title and/or add in appropriate keywords
ï€
Copyright. Put in the copyright year
3.
Execute NetgearUtils > Set PDF Metadata for Book
Custom Tools Reference
114
Production Guide
Creating Useful Metadata (Optional)
When adding data for document properties, consider the following:
•
Use a good descriptive title in the Book Title field. The filename of the document should appear in the Search Results dialog box.
•
Always use the same field for similar information. For example, do not add an important term to the Subject option for some documents and to the Keywords option for others.
•
Use a single, consistent term for the same information. For example, don’t use biology for some documents and life sciences for others.
•
Use the Author option to identify the group responsible for the document. For example, the author of a hiring policy document might be the Human Resources department.
•
If you use document part numbers, add them as keywords. For example, adding doc#= m234 in Keywords could indicate a specific document in a series of several hundred documents on a particular subject.
URL Tools
The URL tool helps to ensure that URLs are active when you make a PDF from a
FrameMaker book. There are two sets of URL tools as follows:
•
When the book is active, the NetgearUtils menu displays the URL Tools menu with two commands for fixing existing URLs in documents:
-
Create URL Report tells you which URLs need attention
-
Apply Character Tag to URL Markers. These tools are for fixing existing URLs in documents. Fixes some of the broken URLs. You might have to use the Insert
URL command to reinsert the others to get a clean report.
•
When a document file is active, the NetgearUtils menu displays an Insert URL command.
This tool ensures an active URL is inserted into the document.
Note:
After incorrect URLs are fixed in older documents and when users start using the Insert URL command to automatically insert and tag URLs, the URL report will be clean and there will be no issues that need attention.
These commands help you have active URLs throughout your book:
•
•
Apply Character Tag to URL Markers
•
Note:
You can put links in our documents to Internet resources that are not owned by NETGEAR, but do this with discretion. You can link to technical standards or organizations such as IEEE. However, do not link to commercial documents owned by competitors or other private companies.
Custom Tools Reference
115
Production Guide
Background Information
FrameMaker requires that the following two things happen so that a URL is correctly converted to an active PDF link:
•
The text of the URL has the Jump character tag applied to it.
•
In front of the URL text, there is a hypertext marker that contains the text “message URL
<URL>" where <URL> is the actual URL, such as www.netgear.com. The marker itself needs to have the same character tag (Jump) applied to it.
For Example, if you want the text "NETGEAR website" to be an active link in a PDF that goes to http://www.netgear.com, you would perform the following steps.
Below is the manual process. The Insert URL command does all of these steps for you.
1.
Type NETGEAR website in the document text.
2.
Apply the Jump tag to the text so it looks like this: .
3.
Put the cursor in front of the text and select Special > Hypertext... to insert a hypertext marker in front of the text.
4.
In the Hypertext dialog, select Go to URL for the Command. Message URL appears in the
Command box.
5.
After Message URL, type www.netgear.com.
6.
Select the New Hypertext Marker button to insert the hypertext marker into the text so it looks like this:
NETGEAR website
.
7.
Check that the marker has the Jump tag applied. If not, apply the Jump tag to the marker.
URL Report
The URL report tool presents various information about the URLs in the document. The information does not necessarily indicate errors, but some of the information could be indicating errors that need your attention. You need to review the report and decide if any fixes are needed and then make the fixes.

To generate the URL report:
At the book level, Select NetgearUtils > URL Report.
The three columns provide different types of information to help you determine whether or not there is an error and what if anything might be done to correct it.
1.
The left column lists the URL markers. Select an entry to open the document and go to the marker. If it starts with something other than Message URL, there is a problem with the marker. Column 3 provides a message to help you determine the fix.
2.
The middle column shows the URL as it appears in the marker. You might spot errors in the
URL such as a misspelling. Also, you can quickly check that all of the URLs in your document work, by selecting the links in the middle column.
Note:
The tool does not do any link checking to ensure the URL target is live.
Custom Tools Reference
116
Production Guide
3.
The right column provides messages to help you determine what the situation is.
For example in
the left column in the third row says that the Hypertext marker is untagged or not available. The middle column shows that the “m” is missing from com. There is no additional information provided in the Message column on the far right. Fix the typo and check the tagging. If all looks correct, rerun the report to see if the error disappears. If you still get errors, check the URL again or use the Insert URL command to reinsert the URL.
Opens the document
Opens the website
Looks like a typo here
Figure 20. Report on URLs in a book
Some of the situations that are reported:
1.
There is text that has the Jump tag applied to it, but there is no marker associated with the text.
This could be because the Jump tag is applied to text that is not supposed to be an active
URL. It could also be that the marker was never inserted, accidentally deleted, or something else. The tool reports the situation, and you decide what the issue is and correct it. For example, you can retag the text if it is not an active URL or use the Insert
URL command to re-create the URL.
Note:
In our manuals routerloginl.net is bolded because we tell the user to type it into the URL box of their browser. If you applied the Jump tag instead of the
Bold tag and did not make it a hypertext marker (which it should not be), the report flags it. The fix is to retag it with Bold.
2.
The URL text and the marker text do not match.
Custom Tools Reference
117
Production Guide
The text you typed into the document and the text you typed into the hypertext dialog box after message URL do not match. This could be intentional like in the example above where NETGEAR website is the URL text and www.netgear.com is the marker text. The tool reports the situation and you have to decide whether or not to fix it. Use the Insert
URL command to re-create the URL if you decide it needs fixing.
3.
There are URL markers that do not have the Jump tag applied to them.
As explained above, the URL text and the URL marker need the Jump tag applied. If the error message tells you that you have untagged URL markers, run the Apply Character
Tag to URL Markers command to fix this problem throughout the book.
Note:
This is the only situation that the Apply Character Tag to URL Markers command fixes.
4.
There is a URL marker with the Jump tag applied, but the character that follows it does not have the URL text.
This could happen if you forgot to insert the URL text or apply the character tag to the
URL text. You have to review the URL and determine how to fix it. Use the Insert URL command to re-create the URL.
Apply Character Tag to URL Markers
Book-level command.
The Apply Character Tag to URL Markers does not apply the Jump character tag to the actual
URL text. It applies the Jump character tag only to URL Hypertext markers. Use this command when the URL Report indicates that there are URL markers that do not have the
Jump tag applied to them.
There is no way for the tool to know if specific text is supposed to be a URL and even if some assumptions are made, such as any text that starts with http://, it is too risky and too slow to try to apply the character tag to the actual URL text.

To apply the character tag to all URL markers:
At the book level, select NetgearUtils > Apply Character Tag to URL Markers.
Custom Tools Reference
118
Production Guide
Insert URL

Use this command to insert a new URL or to re-create a URL that has errors.
To insert a URL:
1.
At the document level, place your cursor where you want the URL to be.
2.
Select NetgearUtils > Insert URL to display the following dialog box:
3.
Complete the fields in the dialog box:
Insert a complete URL. Type the complete target URL into this field. This is the marker text, and is also used for the document text if you leave the next field blank.
Insert text to be displayed in the document. This optional field lets you provide text that the reader clicks on to go to the target URL. For example, it might read NETGEAR website. If this field is left blank, the marker text is used for the document text.
4.
Click OK to insert the URL into the document.
Note:
The Jump character tag includes the carriage return if the URL is at the end of a sentence and not followed by a period. This is the expected behavior.
Template Conversion Tools
The Update Current Book to New Templates menu provides commands for converting books from the old look to the latest templates. See
Chapter 9, Old Style to New Conversion Tutorial
for detailed instructions on how to use these tools.
•
Import Formats from Latest Templates into Current Book
•
Convert Figures/Notices Tables to Paragraphs
•
•
•
•
Add/Setup GenFiles, Numbering and Update Book
Custom Tools Reference
119
Production Guide
Import Formats from Latest Templates into Current Book
This command uses the templates installed into the ~NetgearTools/Templates folder to import the formats and settings into the current book. The settings include the new paragraph tags, character tags, system variables, reference pages, and master pages.

To use this command:
Select the book, and then select Import Formats from Latest Templates into Current
Book.
While the command executes, FrameMaker opens all the book files and applies the template settings and formats. A dialog box displays when the command completes.
This command uses the following algorithm to identify which template to use for importing formats. If you get an error that the command cannot open Unknown Template.fm, make sure the first paragraph has the correct tag so the command can identify it and use the correct template.
1.
Look at the first paragraph in the main flow.
2.
If the tag is:
a. ta_appendix_title, the command uses the Appendix Template.fm template
b. tc_chapter_title, the command uses the Chapter Template.fm template
c. ti_index_title, the command uses the Appendix Template.fm template
d. td_document_title, the command uses the Frontmat.fm template
e. Otherwise the document is of unknown type and the command uses the Unknown template.fm. This file does not exist and is, therefore, an error
Convert Figures/Notices Tables to Paragraphs
This command converts images, figures, notes, warnings, and cautions out of the table formatting used in the old templates and applies the new tags. Anchored frames that house the images and the figure caption may need to be adjusted to align with the paragraph.

To use this command:
Select the book and then select Convert Figures/Notices Tables to Paragraphs.
If a dialog box with the message, Select Text to Convert, displays, it means the document has conditional text that will not be converted. The warning is coming from FrameMaker and not the tool itself. In these cases, wait for the command to finish, and manually unhide the conditional text, and run the command again (assuming you want the hidden text converted).
Custom Tools Reference
120
Production Guide
Remap Old Tags to New Tags
This command uses the RemapConfigFile.fm file to map document elements tagged with the old tags to the new tags with the new table, paragraph and character settings. If you open the file, you see the document elements retagged and in the new look. You still have to page through the files and do some cleanup. See
cleaning up the files.

To use this command:
Select the book and then select Remap Old Tags to New Tags.
If you see any document elements that appear to be using old tags, it means
RemapConfigFile.fm does not have a mapping for that old tag. You need to notify the person who owns RemapConfigFile.fm so they can add it, map it to the correct new tag, and notify everyone there has been an update to the file.
Fix Cross-Reference Links
The Fix Cross-Reference Links command fixes broken cross-references in the book by re-creating the connection between the source (marker) and the target (cross-reference).
This command makes two passes over the book. The first pass fixes the marker text by deleting the current marker and re-creating it with new text, and the second pass updates all cross references to point to the new markers.

To use this command:
Select the book and then select Fix Cross-Reference Links. No report is generated.
Background Information
In unstructured documents, FrameMaker uses cross-reference markers to indicate the destination of a cross-references (in other words, where the cross-reference points to).
For example, if you insert a cross reference to Figure 3, FrameMaker inserts a cross-reference marker in the paragraph for Figure 3 and the marker contains the following text in the old template style:
<The Paragraph Object Unique Id> : <The paragraph tag> : <The paragraph text>
Example,
34567: fg_figure: Figure \ 2-2
In the new template style, there is no fg_figure (instead it is now called fg1_figure) and the figure text has changed to Figure 2.
The conversion from the old style templates to the new style changes the tag, but it does not update the marker text to the new tag and new text. After the conversion, the marker should have looked like this, but it does not.
34567: fg1_figure: Figure 2.
Custom Tools Reference
121
Production Guide
The cross-reference link still works in FrameMaker because FrameMaker uses only the
Paragraph Object Unique Id, which stays the same before and after the conversion. The cross-reference link does not work when you make the PDF because the entire and correct marker text is needed in PDF destinations.
Cleanup Catalogs
The Cleanup Catalogs command uses the RemapConfigFile.fm file to delete old paragraph, character, and table tags from the paragraph, character, and table catalogs.

To use this command:
Select the book, and then select Cleanup Catalogs.
When this command completes, a report displays that tells you by chapter which obsolete tags could not be deleted because they are in use. The file names in the report are links that open the corresponding files when you click on them.
Figure 21. Clean Up Catalogs report
Use the report to:
•
Go into the files and do any necessary retagging.
•
Consider whether RemapConfigFile.fm needs additional entries, and if so convey them to the file owner.
After running this command, your catalogs should be free of the old tags so that you do not inadvertently tag something with an old tag.
Custom Tools Reference
122
Production Guide
Add/Setup GenFiles, Numbering and Update Book
After a template conversion, use this command to update the numbering and to regenerate the contents and index files. When it completes, it updates and saves the book.
This command requires that your numbering settings for Chapter, Page, and Paragraph be set correctly. It relies on that information to update the chapter, page, and paragraph (figures and tables) numbering. These properties should be set correctly in the templates so that when you perform the template update they are applied to your book files. However, if after running this command, the numbering is off, check that the files have the following settings, make corrections manually as needed, and run the command again.
•
Pagination. Next Available/Delete Empty Pages
•
Page numbers. As specified by your Numbering properties. Page Numbers should start with 1 in the front matter and continue numbering from previous page in all subsequent files.
•
Tables. As specified by your Numbering properties for paragraphs. The first table is 1 and number sequentially through the rest of the book.
•
Figures. As specified by your Numbering properties for figures. The first figure is 1 and number sequentially through the rest of the book.
•
Footnotes. As specified by your Numbering properties for figure or table footnotes.
The first figure or table footnote is 1, and they number sequentially through the rest of the book.
•
Chapter/Appendix numbers as appropriate. As specified by your Numbering properties, which should be set as follows:
-
Chapter 1. First page #: 1; Format: Numeric (14)
-
Subsequent chapters. continue numbering...
-
Appendix A. First page#: 1; Format: ALPHABETIC (N)
-
Subsequent appendices. continue numbering...

To use this command:
Select the book, and then select Add/Setup GenFiles, Numbering and Update Book.
Sometimes this tool introduces a Color Description inconsistency message. To fix this error, open either the front matter, index, or contents file in your Templates directory, and select File
>Import >Format to import only the color definitions from one of these files. These files contain the newest color definitions.
Custom Tools Reference
123
Production Guide
Figure 22. Reapply templates to fix color description error
Update Converted Files
New revisions of the templates come out from time to time and using these tools will ensure that all manuals stay up to date - even after they’ve been converted. If tags, styles, or formats have been obsoleted and new ones added, use these tools to update your converted files.

To update already converted files:
1.
Be sure to update the NetgearTools>Templates folder with the latest templates.
step 3, Copy/paste the latest Manual Templates files into the Templates folder:
2.
Apply the updated templates to the book:
a. Import Formats and Latest Templates into Book
b. Remap Old Tags to New Tags
c. Cleanup Catalogs
d. Add/Setup GenFiles, Numbering and Update Book
3.
Page through the files and do any needed cleanup.
Custom Tools Reference
124
9.
Old Style to New Conversion Tutorial
Convert old documents to the new templates format
9
This chapter explains the process and best practices for using the NetgearUtils tools described in
. For information about how to use the NetgearUtils tools, see
This chapter walks through the 3-phase conversion process:
•
•
Finalize the Book File Set in FrameMaker
•
•
•
•
•
Update to Newest Version of Template
Note:
Although these steps can be done in a different order, this order seems to be the most straight-forward and least time consuming.
125
Production Guide
Work on the Book Files Folder
These procedures are performed on the files folder for the book. Working on the book files folder involves the following tasks:
•
Update the Images directory
•
Update the front matter
•
Update the contents, index, and compliance appendix
•
Clean up book files folder

To update the images directory:
1.
Open the folder that houses the book source files.
2.
Rename the Images folder to Images.
The conversion tool looks for a folder named Images. If needed, rename the folder to
Images and update the book path to read this folder.

3.
Open the templates Images folder and copy/paste SideBanner.jpg into your book Images folder. If this image does not import during the conversion, import it by reference manually.
To update the front matter:
1.
Rename the original Frontmat.fm to FrontmatOLD.fm.
This is temporary. You will delete the FrontmatOLD.fm file after you copy/paste the product image from the old cover to the new cover, and import the old variable definitions.

2.
From the templates folder, copy and paste the Frontmatter.fm file in to the book folder.
To update the contents, index, and compliance appendix:
3.
From the templates folder, copy/paste these files into the book folder:
a. FullManualTOC
b. FullManualIX
c. Appropriate compliance appendix
Note:
Adding the front matter, contents, index, and compliance files directly, instead of using the tools to convert the originals, ensures that the correct content is used, that all variables are included from the new templates, and that all hidden tags are applied. This saves a lot of time in the Cleanup stage.

To clean up the book files folder:
Delete these old files from the book folder:
•
Preface.fm
•
TOC.fm
•
Index.fm
•
Vardefs.fm
Old Style to New Conversion Tutorial
126
Production Guide
Finalize the Book File Set in FrameMaker
These procedures are performed with files open in FrameMaker. The goal is to have a finalized set of book files before starting the conversion.

To finalize the front matter:
Open both the Frontmat_old.fm and new Frontmat.fm files.
1.
Copy/paste the cover image from the old to the new file.
2.
Import the old variable definitions in the vardefs.fm file into only the new Frontmat.fm file.
This creates a combination of old and new variable definitions in one file to help you in
step 3, Select NetgearUtils > Variables > Edit Variable Definitions in Book.
Note:
Do not import old definitions into the other files.

3.
Close both of the files.
To finalize the contents, index, and compliance files:
Open the book file in FrameMaker.
1.
Delete the Preface from the book.
2.
Make sure the book has the following files that you copied into the file folder:
•
FullManualTOC.fm
•
FullManualIX.fm
•
Correct compliance appendix for the product.
Update the Book Variables
The templates provide a standard set of variables to be used across all NETGEAR manuals.
In these procedures you will use the custom variable tools to reduce your book variables to the standard set, plus any additional variables that are unique to your book.

To list and edit the book variables:
1.
Select NetgearUtils > Variables.
2.
Select NetgearUtils > Variables > List of Variables... to get a report of the variables in the original book. Rename this file so that it is not overwritten the next time you run the command.
Old Style to New Conversion Tutorial
127
Production Guide
3.
Select NetgearUtils > Variables > Edit Variable Definitions in Book.
You can delete variables that the report shows are not used in the book except the Book
Title and Keywords variables. The Book Title and Keywords variables are not used in the book, but are accessed by the Set PDF Metadata for Book command to populate the metadata dialog box within FrameMaker (File > File Info). When you make a PDF from
FrameMaker, the metadata is then transferred to the PDF to make the PDF more accessible to search engines on the web.
Edit and modify the remaining variables. See
the standard variables.
Note:
You can add variables that are not listed in the template, but do not delete any of the standard ones.

Make sure you set the following variables because they are need by the templates and the tools:
•
Book Title. This variable is not used in the book, but is needed for the Set PDF
Metadata in Book command. This command puts the metadata onto the PDF when you generate a PDF.
•
Keywords. This variable is not used in the book, but is needed for the Set PDF
Metadata in Book command. This command puts the metadata onto the PDF when you generate a PDF.
•
Document part #. Populates the part number on the cover and history table on page
2. Copy/paste the part number from the old variable definitions and delete all other variations of part number variable definitions.
•
Document Title. Populates the book title on the front cover. Do not use the book type in the definition. For example, make it ReadyNAS for Business, and not ReadyNAS user manual for Business.
•
Type of Manual. Populates the subtitle area below the book title on the front cover with the type of manual. For example, User Manual or CLI Manual.
•
Publish Date. Populates the date on the front cover
•
Product Name (Long). Populates various areas of the compliance chapter that require the product name. It also populates the title as it appears in the front matter, and the chapter and appendix headers.
4.
Select Commit to commit the variable definition changes you have made so far. The commit propagates all of the changes you have made to all of the files in the book.
To pare down the book variables:
If you have variables in the book that are used in the book, but are not on the standard variables list, you can either leave them as is or consolidate the variables to the standard list.
1.
Select NetgearUtils > Variables > Edit Variable Definitions in Book.
2.
Copy the definition from a non-standard variable into the standard variable.
Old Style to New Conversion Tutorial
128
Production Guide
3.
Search the book for the non-standard variable and replace it with the standard one.
4.
Do this for each non-standard variable that you want to consolidate.
5.
Run the report again and delete the non-standard variables that are now no longer used in the book.
Run the Conversion Tools
The commands for converting an older book to the new templates or updating an already converted book to the latest templates are on the NetgearUtils > Update Current Book to
New Template menu. When you execute any of the commands, all of the book files open in tabs.
Apply this command first.
Figure 23. List of template update commands
The following procedures walk you through the conversion commands to accomplish the following steps:
•
Update to new templates
•
Convert notice tables to paragraphs
•
Remap tags from old look to new tags
•
Fix cross-reference links so they are active in the PDF
•
Cleanup catalogs so you only have the new set of tags
•
Set up numbering, generated files, and update book

To run the conversion tools:
1.
Select the Import Formats from Latest Templates into Current Book command to read the templates stored in the NetgearTools > Templates folder and applies them to the files in the book.
2.
Select Convert Figures, Notices Tables to Paragraphs to convert tables formerly used for graphics, notes, warnings, cautions, and the like, to text. Ignore book errors at this point.
•
The older style used tables to format figures and notices. This command only needs to be run when a book is first converted from the old look to the new templates.
Old Style to New Conversion Tutorial
129
Production Guide
•
Although this command removes the table formatting and applies the new tags, some
cleanup needs to be done as explained in
3.
Select Remap Old Tags to New Tags to read the RemapConfigFile that resides in the
NetgearTools folder.
4.
Select Fix Cross-Reference Links so that all cross-references work when you generate the
on page 121 for more information. This command only
needs to be run when a book is first converted from the old look to the new templates.
5.
Select Cleanup Catalogs to remove old paragraph, catalog, table, and cross-reference tags left over from the old templates. It also removes old master pages and references pages.
6.
This command also generates a Cleanup Catalogs Report that shows any unresolved tag issues. Ignore this report for the time being. Some issues should be resolved during Phase
II when you clean up the files. You will reapply this command later.
Note:
Please do not modify the RemapConfigFile yourself; any changes you make are lost when a new RemapConfigFile file is released.
7.
Select Add/Setup GenFiles, Numbering and Update Book to set the pagination, page numbers, and chapter/appendix numbering.
Ignore any book generation errors for the time being. If a color description error occurs see
Note:
If the chapter and page numbering is still wrong. Run the command again. If that does not fix it, check your numbering properties for each file as explained in
Add/Setup GenFiles, Numbering and
8.
Sometimes, this command introduces a Color Description inconsistency message. To remedy this error, use the File > Import > Format command to import ONLY the color
Old Style to New Conversion Tutorial
130
Production Guide
definitions from either the front matter, index or TOC file. These are the new files that were added in
on page 126 and contain the newest color definitions.
Figure 24. Fix the Color Description error
Clean up the Files
You work with each of the individual files to resolve formatting issues, and clean up the
Master and Reference pages. This is where you will spend the most time because these are primarily manual processes.

To clean up the front matter, contents, and index files:
1.
Clean up the Frontmat.
a. If you did not do this step previously, open the Frontmat_Old.fm file and the new
Frontmat.fm file. See
b. Copy/paste the product image from the old file into the anchored frame in the new file.
c. Close and delete the Frontmat_Old.fm file from the book folder; it is no longer needed.
d. On the new Frontmat.fm file, make sure these variables display correctly:
•
Document Part #
•
Document Title
•
Type of Manual
•
Publish Date
e. Save and close the file.
2.
Clean up the FullManualTOC.fm file.
Old Style to New Conversion Tutorial
131
Production Guide
If you deleted the old TOC and already copy/pasted the new TOC into the source folder, there is nothing to be modified on the FullManualTOC.fm file. See
Save and close the file.
3.
Clean up the FullManualIX.fm file.
If you deleted the old IX and already copy/pasted the new IX into the source folder, there
is nothing to be modified on FullManualIX.fm file. See

Save and close the file.
To clean up the chapter and appendix files:
This is where you’ll spend most of your time.If the big chapter number does not show up, you may need to apply the new master page.
1.
Select Format > Page Layout > Master Page Usage and select chap_cover.
2.
Clean up the first Page:
•
Remove the extra line above the Chapter or Appendix title;
•
At the end of the title, press return, and add a subtitle, if needed.
•
Change the first paragraph from p1_body to p0_body.
Old Style to New Conversion Tutorial
132
Production Guide
Before cleanup
After cleanup
3.
Remove extra spaces above and below the notes, graphics, tips, warnings, etc.
These spaces are generated with the Convert Figures/Notices Tables to Paragraph command, and have to be manually removed.
Remove extra spaces, tags, and so on.
Old Style to New Conversion Tutorial
133
Production Guide
4.
Modify the anchored frames that were not automatically aligned correctly:
The command converted most anchored frames to:
•
Below Current Line
•
Right.
•
width: 6.25" (or 6" to align with the paragraph above)
•
height: can stay as it is
Change step headers to h4_head and align Figure captions
From this....
To this....
5.
Modify tables, if needed.
Old Style to New Conversion Tutorial
134
Production Guide
The conversion tool should do most of this, but on occasion you may need to:
a. Add the yellow header (30% yellow)
Select Table > Custom Ruling & Shading and set definitions as shown.
b. Add or remove Table titles, as needed.
6.
Additional cleanup tasks:
•
Apply H4_head to step headers.
•
Realign graphics, as needed.
•
Realign figures, as needed
•
Remove extra carriage returns throughout each file.
•
Other cleanup tasks as you see necessary in the document.
7.
Clean up the Master Pages.
To keep the files as clean as possible, check the master pages of each file. Cleaning these will resolve many Cleanup Catalog issues you may have gotten earlier. Each template contains only three (3) master pages. Delete all other master pages.
Frontmat
•
Book Cover
•
Left
•
Right
TOC
•
TOC_First
•
Left
•
Right
Chapters and Appendices
Old Style to New Conversion Tutorial
135
Production Guide
•
chap_cover
•
Left
•
Right
IX
•
Index_First
•
Left
•
Right
8.
Clean up the Reference Pages. The reference pages on all the templates are exactly the same. All other reference pages should be deleted.
•
TOC
•
IX
•
Reference
9.
Reapply NetgearUtils > Remap Old Tags to New Tags and NetgearUtils > Cleanup
Catalogs to get a new list of tag issues, which should be shorter at this point.
10.
Resolve issues that show up in the Cleanup Catalogs Report, if any.
Note:
The following Tables might show up in this report but they need to be resolved manually by going to the Table Designer and deleting them from the catalog:
•
Warning
•
Img1
•
Img2
•
Img3
•
Note
•
Note_2
They cannot be resolved through he RemapConfigFile because it causes the Notes,
Warnings, etc, to stay in tables rather than being converted to text.
Note:
If there are still tags that show up in the CleanupCatalogReport, have someone else look at it to see if the tags can be mapped in
RemapConfigFile.fm.
11.
Save and close each file.
Old Style to New Conversion Tutorial
136
Production Guide
Use Additional Tools
Use the other tools available on the NetgearUtils menu to finish the conversion process.
They are straightforward and easy to use. For more information, see
.
These commands require that all book files be closed.
•
•
•
•
Update to Newest Version of Template
After a book is converted from the old look to the new templates, you can easily update it to newer revisions of the new templates.

To update to a newer template version:
Step through all the commands on the NetgearUtils menu.
Note:
You can skip the Convert Figure/Notices Tables to Paragraphs and the Fix Cross-References Links commands. There is no harm in running them again, it’s just unnecessary.

To check the big Chap/App numbers on first page of each file.
Delete the extra Big Num that might show up on the front page.
Old Style to New Conversion Tutorial
137
A.
Install Custom Tools
Add the NetgearUtils menu to FrameMaker
A
NETGEAR contracted with an outside vendor (Tassos Anastasiou [email protected]) to create a set of custom add-on tools for FrameMaker. The tools automate time-consuming tasks commonly done when converting documents from the old format to the new format and starting and finalizing documents.
The following topics are covered:
Note:
These tools are for the sole use of NETGEAR employees and contractors, and cannot be given to anyone else, or to any other company.
138
Production Guide
About the Tools
This custom menu, called NetgearUtils, appears on the FrameMaker book menu bar, but has to be installed before it shows up on the menu bar. The NetgearUtils menu only shows up when a FrameMaker book file is open and selected.
Figure 25. NetgearUtils menu options
These tools are extremely important when converting older docs into the new format, and for keeping already converted docs up-to-date with the latest NETGEAR style.
Basic Installation Steps
1.
Create a NetgearTools folder in your FrameMaker 9 installation folder.
2.
Copy/paste the Tool files into the NetgearTools folder.
3.
Copy/paste the Template files into the Templates folder.
4.
Modify the maker.ini file.
5.
Launch FrameMaker.
Tools Installation

To install the tools:
1.
Create a NetgearTools folder in the FrameMaker 9 installation folder:
•
Windows XP. C:\Program Files\Adobe\FrameMaker9\NetgearTools
•
Windows 7. C:\Program Files (x86)\Adobe\FrameMaker9\NetgearTools
2.
Copy/paste the most recent Tool files into the NetgearTools folder you just created:
a. You will find them on either geardog (external) or the V drive (internal):
Geardog. ~/4TechPubs/NetgearTools
V drive. ~\Engineering\TechnicalPublications\Tools\NetgearTools
b. Copy/paste the following files. You do not need to copy the two Zip files in there.
•
Templates folder (has a ReadMe.txt)
•
Edit-maker-Dot-ini-File.txt
•
netgearutils.dll
Install Custom Tools
139
Production Guide
•
pdfsettings.fm
•
RemapConfigFile.fm
•
remapper.dll
•
remaptoolinstructions.txt
•
report.tpl
3.
Copy/paste the latest Manual Templates files into the Templates folder:
a. You can find them on either geardog or the V drive:
Geardog. /ngreng/4TechPubs/Templates - Current/Manuals
V drive. V:\Engineering\TechnicalPublications\Templates\Templates -
Current\Manuals
b. Copy/paste all of the files:
•
Images folder
•
AppCompliance_Adapters
•
AppCompliance_Wired
•
AppCompliance_Wired_Powerline
•
AppCompliance_Wireless
•
Appendix Template.fm
•
Chapter Template.fm
•
Frontmat.fm
•
FullManualIX.fm
•
FullManualTOC.fm
•
NewTemplates book file
•
Production Guide
4.
Modify the maker.ini file.
a. Open the maker.ini file in a text editor.
C:\Program Files\Adobe\FrameMaker9\maker.ini
b. Search for APIClients and find the second instance of the API Clients area.
It looks like this:
[APIClients]
ï€
;------------------------------ API Clients
------------------------------
ï€
;ClientName=ClientType, [facet, format_id, vendor_id, display_name, ]
description, path, mode, optional file extension for filter
c. Copy the following 3 lines into the maker.ini file. You can copy the lines from here or from the Edit-maker-Dot-ini-File.txt file in the NetgearTools directory.
Install Custom Tools
140
Production Guide
Note:
Make sure the directory name within your FrameMaker9 installation
(NetgearTools) is spelled exactly the same as the reference to NetgearTools in the following lines. Case does not matter. A mismatch causes the NetgearUtils menu to not display when to start FrameMaker and select a book.
;Netgear Tools
NetgearUtils=Standard, Netgear Custom Tools, netgeartools\netgearutils.dll, maker
NetgearRemapper=Standard,Netgear Template Remap
Client,NetgearTools\remapper.dll, maker
d. Paste these 3 lines before the line that starts with ;ClientName=, (they can wrap):
e. Save and close the maker.ini file.
5.
Open a book in FrameMaker.
Select the book and look at the menu items. You should see the NetgearUtils menu between the View and Window menus.
See
Chapter 8, Custom Tools Reference
for a detailed description of these tools, and how they work.
Install Custom Tools
141
B.
Templates Reference for Manuals
Variables, front matter, master pages, reference pages
B
This appendix supplements the tagging and formatting information provided in the chapter.fm file of our templates for manuals. Refer to the chapter.fm file for tag specs and usage guidelines.
This appendix covers the following topics:
142
Production Guide
Variable Definitions
There is a set list of standard variables that are used in the manual templates and accessed with the commands on the NetgearUtils > Variables menu within FrameMaker. Older documents have a FrameMaker variable definition file called vardef.fm, which defines project-specific terms used throughout the book. This file was not always accurate and often contained invalid, legacy variable definitions left over from other documents.
With the custom Variables menu, the vardef.fm file is no longer needed. See
on page 127 for information about the best way to migrate away from the
vardefs.fm file approach and to edit, update, and delete variables. You can find this information in
Table 5. Variable definitions and descriptions
VARIABLE NAME
Book Title:
VARIABLE DEFINITION
USAGE
Production Guide
Add/Setup GenFiles, Numbering and Update Book
on page 123Generates the “Title”
hone
Company Name: NETGEAR, Inc.
file info with the Set PDF Meta data for Book NetgearUtils tool.
Frontmat.fm, page 2. Generates the “Author” meta data file info with the Set PDF Meta data for Book
NetgearUtils tool.
In-line as needed.
Company Name in line: NETGEAR
Copyright: © NETGEAR Generates the “Copyright” meta data file info with the Set PDF Meta data for Book NetgearUtils tool.
Format: XXX-XXXX-XX Document Part #:
Document Title:
Part Number TBD
Production Guide Front cover. Apply the
td_document_title paragraph tag.
Do not include the type of manual
(i.e., user manual). See Type of
Manual variable.
In line as reference within the doc.
Document Title™:
Installation Guide Title:
Product Installation Guide
In-line as reference within the doc.
IP Address: 192.168.1.1
Check also for subnet changes, etc.
Keywords
NETGEAR® Product User
Manual
NETGEAR Technical
Publications Production
Guide
Generates the “Keywords” meta data file info with the Set PDF Meta data for Book NetgearUtils tool.
Templates Reference for Manuals
143
Production Guide
Table 5. Variable definitions and descriptions
VARIABLE NAME
Product Family:
VARIABLE DEFINITION
USAGE n/a Check with engineering/PLM for correct family.
Product Family in line: n/a
Product Model #:
Product Name (long):
Product Name (short):
Model Number
Production Guide
Production Guide
Check with engineering/PLM for correct family.
Example: MS2110.
ï€
When used on front cover, apply the td_document_title paragraph tag.
Example: Stora MS2110. When used on front cover, apply the td_document_title paragraph tag.
ï€
Generates the “Title” meta data file info with the Set PDF Meta data for
Book NetgearUtils tool.
Example: Stora
ï€
When used on front cover, apply the td_document_title paragraph tag.
Product Name (™/®):
Publish Date:
Release Number:
Resource CD:
Product Name™/® & Model Mandatory field use in Compliance sections.
ï€
Use ™/® as required by product.
ï€
Example: NETGEAR® Stora™
MS2100
February 2012 Front cover & page 2 of
Frontmat.fm
Release 1.0
Resource CD
Front cover (Frontmat.fm)
In-line as reference to product resource CD.
SAR Level (W/kg):
SSID:
Type of Manual:
Version #
<insert value; get from engineer>
NETGEAR
Production Guide v1.0
Mandatory for Wireless/Adapter
Compliance.
ï€
Check with engineer for numbers.
Used mostly for routers. Check with engineer.
Hardware/Software/Reference/Inst all Guide/etc.
ï€
Use on the Front cover;
ï€ apply the Subtitle_Cover paragraph tag.
Front cover (Frontmat.fm)
Templates Reference for Manuals
144
Production Guide
Front Matter, Page 1
Hidden text automatically sets Reading Language Option for
508 ADA compliance in a PDF file.
ï€
Uses the Chap_App_White character tag. DO NOT DELETE !!!
Use the variable
ï€
Type of Manual
ï€
and apply the
Subtitle_Cover paragraph tag.
For doc title,
ï€
use any variable or variables that apply,
ï€
such as Model #, Product
Name, etc.
, and apply the td_document_title paragraph tag.
Embedded anchored frame to add a product photo.
ï€
Adjust size, as necessary.
Lives on the master page
ï€
Uses the variables:
ï€
- Publish date
ï€
- TP Part#
ï€
- Version Number
Templates Reference for Manuals
145
Production Guide
Front Matter, Page 2
Uses the variables:
ï€
- Copyright
ï€
- Company Name
Paragraph tags:
ï€
Headings: hf1_head; hf2_head; or hf3_head
ï€
Body text: legalese or legalese_indent
ï€
Bullets: legal_bullet or legal_bullet2
ï€
Notes: legal_note
Uses the variables:
ï€
- Document Part #
ï€
- Version Number
ï€
- Publish date
History Table Paragraph tags:
ï€
CellHeading
ï€
CellBody
Templates Reference for Manuals
146
Production Guide
Chapter Tags
Chapter Number: The large “1” on the right is the ChapNum tag. It will auto-generate for each chapter.
Chapter Title: tag is called tc_chapter_title. This tag contains a “hidden” character tag called “Chap_App_White” so that it generates the “1,” “2,” etc, for the TOC in the pdf file.
This is why the chapter title section in the template looks “indented,” but it will align correctly in the doc.
Note:
*For the example below, the “Chap_App_White” tag (1.) is shown as
“magenta”, but it is actually white in the template so that it does not show up in the document.
Subtitle tag: Use after the chapter title, as needed, but before the body.
Associated TOC tag:
•
ChapNumTOC
•
tc_chapter_titleTOC
ChapNum paragraph tag hidden Chap_App_White character tag* tc_chapter_title paragraph tag
Subtitle paragraph tag p0_body paragraph tag b1_bullet paragraph tag with “Heading” cross reference tag.
Figure 26. First Page with “hidden” Chap_App_White character tag showing
Templates Reference for Manuals
147
Production Guide
Appendix Tags
Appendix Number: The large “A” on the right is the AppNum tag. It will auto-generate for each appendix.
Appendix Title: tag is called ta_appendix_title. This tag contains a “hidden” character tag called “Chap_App_White” so that it generates the “A,” “B,” etc, for the TOC in the pdf file. It is white in the template so it does not show up in the document. This is why the appendix title section in the template looks “indented,” but it will align correctly in the doc.
Subtitle tag: use after the Appendix title but before the body.
Associated TOC tag:
•
AppNumTOC
•
ta_appendix_titleTOC
hidden Chap_App_White character tag
AppNum paragraph tag ta_appendix_title paragraph tag
Subtitle paragraph tag p0_body paragraph tag b1_bullet paragraph tag with “Heading” cross reference tag.
Figure 27. First Page with “hidden” Chap_App_White character tag NOT showing
Templates Reference for Manuals
148
Production Guide
TOC Tags
The TOC Title tag is called “toc”, and is only used on the Contents title page.
Associated TOC tags:
•
AppNumTOC: generates the “Appendix A” part of TOC
•
ChapNumTOC: generates the “Chapter 1” part of TOC
•
ta_appendix_titleTOC: generates the appendix title
•
tc_chapter_titleTOC: generates the chapter title
•
ti_index_titleTOC: generates the Index tile
•
h1_headTOC: generates level 1 headings using h1_head tag
•
h2_headTOC: generates level 2 headings using h2_head tag
•
hp1_head_pTOC: generates level 1 headings using hp1_head_p tag
•
hp2_head_pTOC: generates level 2 headings using hp2_head_p tag
•
h3_headTOC: generates level 3 headings using h3_heading tag, but level 3 is not generated in the template.
Note:
There is no associated TOC tag since the TOC title is not generated for the TOC. Also, td_document_titleTOC is not generated in the TOC.
Templates Reference for Manuals
149
.
Production Guide
Templates Reference for Manuals
150
Production Guide
Index Tags
Generates the listing for the index in the TOC. It is not used in the indes.fm file.
ï€
11 pt. Arial regular. First and left indents: 1”. Above paragraph: 14 pt. Below paragraph: 8 pt.
Line space: 14 pt.
Generates the index title.
ï€
24 pt Futura Md regular black. No indents. Above: 7 pt, Below 7 pt. Line Space 13 pt fixed.
Generates the alphabetic index markers in the index.fm file.
ï€
14 pt. Arial, blue, bold, No indents. Above: 15 pt, Below: 3 pt., Line Space: 17 pt.
Templates Reference for Manuals
151
Production Guide
Master Pages
Each template contains only three (3) master pages. All other master pages should be deleted.
Note:
Not all OLD master pages may be listed in the tables below. When converting files from the old format, please DELETE all master pages except for the 3 used in the new templates. Extra master pages may show up in the CleanUpCatalog report when the conversion tool is applied.
Frontmat.fm
New master page names:
Book Cover
Left
Right
Old master page names:
Title Page
Left
Right
Logo
Note:
Other old master pages may not be listed here.
FullManaulTOC.fm
New master page names:
TOC_First
Left
Right
Old master page names: chap_cover
Left
Right
Title Page
LOGO
Blank
Note:
Other old master pages may not be listed here.
Templates Reference for Manuals
152
Production Guide
Chapter Template.fm
New master page names: chap_cover
Left
Right
FullManaulIX.fm
New master page names:
Index_First
Left
Right
Old master page names: chap_cover
Left
Right
Title Page
LOGO
Blank
Note:
Other old master pages may not be listed here.
Appendix Template.fm
New master page names: chap_cover
Left
Right
Old master page names: chap_cover
Left
Right
Title Page
LOGO
Blank
Note:
Other old master pages may not be listed here.
Old master page names:
Note:
Other old master pages may not be listed here.
Templates Reference for Manuals
153
Production Guide
Reference Pages
Each template contains only three (3) reference pages. They are the same three pages for all templates. All other reference pages should be deleted from the files.
The reference page also shows the template revision date.
Note:
Not all OLD reference pages may be listed in the table. When converting files from the old format, please DELETE all reference pages except for the 3 used in the new templates.
Frontmat.fm
New reference page names:
TOC
IX
Reference
Old reference page names:
(No equivalent)
(No equivalent)
Reference note lof lot
Note:
Other old reference pages may not be listed here
FullManaulTOC.fm
New reference page names:
TOC
IX
Reference
Old reference page names:
TOC
Index
Reference note lof lot
Note:
Other old reference pages may not be listed here
Templates Reference for Manuals
154
Production Guide
Chapter Template.fm
New reference page names:
TOC
IX
Reference
FullManaulIX.fm
Reference page names are:
TOC
IX
Reference
Old reference page names:
(No equivalent)
(No equivalent)
Reference note lof lot
Note:
Other old reference pages may not be listed here
Appendix Template.fm
New reference page names:
TOC
IX
Reference
Old reference page names:
(No equivalent)
(No equivalent)
Reference note lof lot
Note:
Other old reference pages may not be listed here
Old reference page names:
(No equivalent)
Index
Reference
Note:
Other old reference pages may not be listed here
Templates Reference for Manuals
155
C.
Office and Laptop Tips
Writer resources
C
This appendix provides departmental information pertaining to staff meetings, and accessing the
ftp://geardog.netgear.com
FTP site and the
http://docs.netgear.com
site, where we publish early user manual releases. It also provides information about maintaining your NETGEAR laptop.
Make an Email Distribution List in Outlook
Extract Files from an Apple Archive (sit) File
156
Production Guide
Desktop Sharing for a Meeting

To share a desktop:
1.
Go to the Adobe site:
http://netgear.acrobat.com
2.
Login using [email protected] for the user name and Welcome1 for the password.
3.
Open the meeting
4.
Start the meeting
5.
Select sharing of desktop screen
6.
Select monitor (first or second screen)
7.
Click Share
8.
Allow guests
9.
Guests log in at:
http://netgear.na6.acrobat.com/r12855961/
Geardog

To access geardog with WS_FTP Pro:

1.
Install IpSwitch WS_FTP Pro if you do not already have it.
2.
Get the user name and password from IT or the technical publications manager.
3.
Go to V:\Engineering\TechnicalPublications\Tools\WS-FTP Pro 9.0\English and double-click on setup.exe to install the software.
4.
Start IpSwitch.
5.
Select the Connection Wizard menu.
6.
Enter geardog for the site name.
7.
Type geardog.netgear.com for the server address.
8.
Enter the user name.
9.
Enter the password.
10.
Accept FTP as the connection type.
To access geardog with your browser:
1.
In Internet Explorer, type
ftp://geardog.netgear.com/
in the URL box.
2.
Enter the user name.
3.
Enter the password.
4.
When you get the Internet Explorer cannot display the web page message, Select Page >
Open FTP Site in WIndows Explorer.
5.
Enter the user name and password again.
Note:
If you don’t see the Page menu in IE, use the View menu to add it.
Office and Laptop Tips
157
Production Guide
docs.netgear.com

To access docs.netgear.com:
1.
Install IpSwitch WS_FTP Pro if you do not already have it.
2.
Get the user name and password from IT or the technical publications manager.
3.
Go to V:\Engineering\TechnicalPublications\Tools\WS-FTP Pro 9.0\English and double-click
setup.exe to install the software.
4.
Start IpSwitch.
5.
Choose the Connection Wizard menu.
6.
Enter docserver for the site name.
7.
Type docs.netgear.com for the server address.
8.
Enter the user name.
9.
Enter the password.
10.
Accept FTP as the connection type.
Note:
To FTP to the docs server from outside NETGEAR, VPN must be running. But sometimes docs.netgear.com is not accessible, and it usually means the log file is full. Contact Kent Robinson so he knows he needs to clear out the log file. [email protected].

To access docs.netgear.com with your browser:
1.
In Internet Explorer, type
ftp://docs.netgear.com/
in the URL box.
2.
Enter the user name.
3.
Enter the password.
4.
When you get the Internet Explorer cannot display the web page message, Select Page >
Open FTP Site in WIndows Explorer.
5.
Enter the user name and password again.
Note:
If you don’t see the Page menu in IE, use the View menu to add it.
Office and Laptop Tips
158
Production Guide
Laptop Maintenance

To check laptop memory
1.
Right-click the My Computer icon on the desktop.
2.
Select Properties.
Memory is shown in the lower right. For Adobe products/Frame, about 3 Gb of RAM is adequate.

To run scans and defragment the disk:
1.
On the Start Menu, select Computer.
2.
Right-click Local Disk (C:). and select Properties.
3.
Select the Tools tab.
4.
Select the Check Now button to run a scan or the Defragment Now button to run a disk defragmentation.
The disk defragmentation takes place the next time you turn on your computer and takes several hours to complete. The best thing to do is to turn shut your computer down, and turn it back on right before you leave for the night to start the scan. In the morning you can log in as usual.
Office and Laptop Tips
159
Production Guide
5.
In the dialog box that displays, select both CHeck disk options as shown, click OK, then click
Yes to schedule the scan for the next reboot. The scan begins the next time you turn on the computer and can take 1-2 hours to complete.

To run virus scans on the C drive:
1.
Select Start > All Programs > ThinkVantage > Maintenance Manager.
2.
Select Scan for virus using Symantec Antivirus.
3.
Clear the other check boxes. It’s generally better to perform one maintenance function at a time. You can come back and run the others one by one as needed.
Office and Laptop Tips
160
Production Guide
4.
Click OK.
Order Software
We order software from CDW (
http://www.cdw.com
). Locate what you want on their site and get the technical publications manager approval for the purchase.
The technical publications manager will then contact Brian Murphy, who is the NETGEAR account manager at CDW. We get a discount through them so it's worthwhile to either login to the NETGEAR account to order or call him. IT can tell you what the NETGEAR log in is.
Phone. 1-877-571-7059
Email. [email protected]
If you purchase with a PO, the technical publications manager will ask Brian for a quote including shipping and tax. Open the PO, and then phone or email him and ask him to place the order under the PO number.
Office and Laptop Tips
161
Production Guide
Remote Access to the V Drive
You can have read-only access to the V drive through the Citrix Web Interface at
http://citrix.netgear.com
and read-write access over VPN.

•
The Citrix web interface provides read-only access.
•
VPN provides read-write access.

To use the Citirx web interface:
1.
Go to http://citrix.netgear.com
2.
If this is your first time, download the Citrix Presentation Server Client from the login page.
Do not log in yet.
3.
If you already downloaded the Citrix Presentation Server Client, log in using your LDAP user name and password.
4.
Click the Atlas - V Drive Corporate Share icon, follow any prompts that appear, and browse the V drive.
To use VPN:
1.
Download the Citrix VPN client from https://pier40.netgear.com and install it.
2.
Start the VPN client and log in with your LDAP user name and password.
3.
On Windows XP go to Start > Run and type \\atlas.netgear.com.
4.
If prompted, log in with your LADAP user name and password, but put \netgear in front of your user name like this:
\netgear user name
ï€ password
5.
Click the Corporate Share folder to access the V drive.
6.
Employees only. Click the Departmental Share folder to access the U drive.
7.
Employees only. Click the Home folder to access your home directory.
Office and Laptop Tips
162
Production Guide
Desk Phones

To initialize a phone:

1.
Plug in the phone if it is not already plugged in.
2.
In the Ext prompt, type the extension number and press OK.
3.
In the password prompt, type the extension number and press OK.
To make and receive calls on another phone from your own extension:
1.
Note the original extension number on a piece of paper.
2.
Press the Menu button.
3.
Press the Up or Down arrow key to locate the Log Out option.
4.
Press the button under Select. and then the button under Log Out.
5.
Initialize the phone with the original extension as described in
6.
If the phone belongs to someone else, follow Steps 3 through 5 to log out when you are done and put the original extension back in.
Make an Email Distribution List in Outlook
A distribution list is a great way to notify people of an event such as when a document is ready for Agile pickup. Put the people who are always notified regardless of the project on the distribution list. When you make your notification, email to the distribution list plus other people who are specific to the project such and the product engineer. These lists work best when everyone has a NETGEAR email. You can put people without a NETGEAR email on the list, but they will not be able to reply to the list.

To make a distribution list:
1.
In Outlook, select File > New > Distribution List
2.
Type the distribution list name in the Name: field.
3.
Use the Select Members and Add Members buttons to add names to your distribution list.
4.
Select Save and Close.
To edit your distribution list:
1.
In Outlook, select Tools > Address Book.
2.
Under Address Book, select Contacts.
3.
Under Contacts, double-click the distribution list you want to edit.
4.
Use the Select Members, Add New, and Remove buttons to edit the distributions list.
5.
Select Save and Close.
Office and Laptop Tips
163
Production Guide
Extract Files from an Apple Archive (sit) File
Download this handy tool:
Free Stuffit Expander
Lab Space
We have two benches in the SPBU lab. They are the 2nd and 3rd benches in the 3rd row, which is the row closest to the door. Currently people have some PCs and units on them. The rule is that these benches are ours and we can take them whenever we need them. These two benches are not officially occupied by engineers.
Office and Laptop Tips
164
D.
DITA Reference
Understanding DITA
D
Use the information here to understand DITA and as a quick reference to DITA elements for tagging DITA content. A complete list of DITA elements can be found on the web. The default
DITA standard has more than 400 elements, and those elements contain attributes, which can be overwhelming at first. A good place to start is with the elements described in this appendix.
165
Production Guide
DITA Introduction
Darwin Information Typing Architecture (DITA) is a topic-based and task-oriented approach to producing content. DITA effectively takes task-oriented and task-based writing a step further by organizing information into modular topics that can be reused.
In DITA there are three types of topics: task, concept, and reference. Each topic covers one subject, and a DITA map organizes a set of topics into an information flow for publication in different formats such as PDF or HTML files. There is also a generic topic for content that has no type.
Writers tag and store individual topics in a component content management system (CCMS).
Anyone with access to the CCMS can retrieve and use the topics. Anyone with a DITA authoring environment can create topics and DITA maps. DITA authoring is about editing
XML text files that conform to the DITA Document Type Definition (DTD).
The DITA DTD declares precisely which elements and references can appear where in the document of the particular type (topic, task, reference, or concept), and what the element contents and attributes are. The OASIS DITA document types are implemented with a set of
DTD modules. Some of these modules are used by every DITA document type; others are only used by topics or by maps, and some are only used in specific specializations. For more information, see
DTD Organization
.
Printed Documents
DITA is independent of style and layout, and therefore, does not currently work well for printed documents. NETGEAR technical publications prints installation guides and flyers.
See the following for information about
DITA-capable page layout
. At the present time, the workflow from DITA to printed documents is complex and expensive.
Localization
DITA can reduce localization costs because the DITA approach to writing results in fewer words and reusable topics. Currently, NETGEAR localizes mostly printed installation guides, so the cost savings to localization is not immediately obvious. In the future, NETGEAR could localize more longer manuals that are not printed. If and when this happens, the cost savings to localization by authoring in DITA could be more evident.
Content Reuse
The most immediate value of DITA to NETGEAR is in content reuse. Many products share identical features in different combinations. DITA would let technical publications combine the applicable topics from a topic database into a product manual. This model would work best for concept and reference topics.
To a lesser degree, DITA would also work for task topics. There is more variation in tasks across our products for the same feature due to inconsistent product specification
DITA Reference
166
Production Guide
implementations by ODMs. The implementation variation means that many task topics for the same feature would need to be maintained and carefully tagged with metadata to prevent a task topic from going into the wrong manual. As the NETGEAR usability team establishes more standards for consistency across all product lines, NETGEAR should get to a point where task variation will reduce.
It is unlikely that sales, marketing, or training would use the DITA topics produced by technical publications without modifying them. The value of content reuse through DITA is lost when the content is modified by the receiving party. Technical support is the most likely group to reuse without modification the DITA topics produced by technical publications.
Storing content in a CCMS would make it easier for technical support to locate topics of interest to publish to the support website.
Some of the value of content reuse by technical support would be in receiving automatic updates to content posted to the support website. However, it is important to be aware that content changes are usually made for updates to newer versions of the product. Technical publications would use metadata to carefully tag the new content. Nevertheless, care would have to be taken by technical support to ensure DITA content for an older product is not updated with content meant for the newer product. It is likely that two or more versions of the product are in the installed customer base, and therefore, as many versions of the content needs to be maintained on the website.
Transition
The technical publications department is small and constantly busy. Documents are released weekly for new products and product updates. The writers have almost zero downtime, which means a transition from the current unstructured FrameMaker authoring system to a DITA authoring system would have to be very carefully managed.
1.
Management needs to provide financial support for tools, training, and DITA expertise.
Without this support, it is not possible to transition the writing team to DITA authoring and production.
2.
Authoring, illustration, conversion, and content management tools are required for the writers.
3.
Writers have to be trained to effectively use their new tools. Training:
4.
Expertise:
a. Project manager to manage the DITA conversion project.
b. XML architect to own the DITA document type definitions (DTDs).
c. Information architect to define the information model.
d. System administrator (or tools specialist) to own the source control system, publishing system, and tools automation.
e. Quality assurance engineer to test style sheets and transforms.
f. A company like
Stilo
to convert documents from unstructured Frame to DITA.
DITA Reference
167
Production Guide
Tools
Authoring
The oXygen tool is a good authoring environment that comes with the features we would need. See
http://www.oxygenxml.com/
.
Structured FrameMaker does not produce true and portable DITA format because of all the
<?Fm Condition> processing instructions in the XML output. It is not producing correct DITA, because it dumps all content into a composite topic type instead of the specific topic type
(concept, task, or reference). Instead of standard DTD files, FrameMaker introduced EDD files – which were similar to DTDs, but not quite the same.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd" [
<!-- Begin Document Specific Declarations -->
<!-- End Document Specific Declarations -->
]>
<?Fm Condition DITA-Prolog AsIs NO_OVERRIDE hide?>
<?Fm Condition DITA-Comment AsIs NO_OVERRIDE hide?>
<?Fm Condition FM8_SYSTEM_HIDEELEMENT AsIs NO_OVERRIDE hide?>
FrameMaker has a View in Notepad option that displays the XML code. However, you cannot edit the XML code or see changes you have not yet saved. The information displayed in
FrameMaker is a rendered version of the underlying XML file. What authors want is the ability to edit the XML files directly and then continue working in FrameMaker.

To make the View in Notepad option semi-usable:
1.
Go to %APPDATA%\Adobe\FrameMaker\10 to change the default text editor.
2.
Open the TextEditorPlugin.ini file in a text editor, and you see this:
[TextEditor]
ï€
TextEditorName=C:\WINDOWS\system32\Notepad.exe
ï€
SaveFileBeforeOpening=No
3.
Edit the file to reference TextPad instead of Notepad and to save before opening:
[TextEditor]
ï€
TextEditorName=C:\Program Files\TextPad\TextPad.exe
ï€
SaveFileBeforeOpening=Yes
4.
Close and restart FrameMaker.
If you attempt to edit the text file that’s displayed, you get an error when you attempt to save. You can close the file in FrameMaker and then make changes in the text editor.
CCMS
Component content management system (CCMS) to make the DITA content readily searchable and available to others.
DITA Reference
168
Production Guide
SVG Rendering
SVG rendering tools. The oXygen authoring tools comes with this installed. Other authoring tools need to have an SVG rendered installed.
•
In DITA binary files (images) can only be referenced. That is, you have an image tag with an href attribute. This works well for jpgs, gifs, and png files for screen captures.
•
Illustrations need to be in SVG format. Adobe Illustrator can output SVG. There are also
SVG editors available. SVG is an XML format for vector graphics. Since the SVG is text, you can edit the text within a DITA authoring tool because most of them are general XML editors that have the DITA DTDs installed with the editor. Companies that localize a lot convert all of their graphics to SVG because it is cheaper to localize strings than binary images.
Note:
SVG is XML that conforms to a different schema than DITA. All XML documents are governed by a schema that describes the structure of a document, message, illustration. For tools to validate the XML document, the document has to declare at the beginning what schema it conforms to.
Training
•
Learning to use the chosen DITA authoring tool.
•
Learning the elements to properly tag the content. The default DITA standard has more than 400 elements, and those elements contain attributes. We would start by mapping
FrameMaker tags to DITA elements. Other DITA elements would be needed, but it would be best to define a core set of elements and attributes to be used.
•
Figure call outs. There are two types of call outs, text and keyed:
-
In text call outs, the labels are superimposed on the image.
-
In keyed call outs, language independent key numbers or letters are superimposed on the image, with a legend providing the explanations for the call out keys displayed outside the image.
-
The keyed method is preferred. The legend is stored in a definition list (dl) within the figure (fig) element. Legends are more easily maintained and more easily localized, as the text explanations are stored as text rather than embedded within the image file
•
Component content management system (CCMS).
•
Documented new processes for reference.
•
Editor needs to know what to look for during an edit.
-
Correct content tagging.
-
Topic-based writing and one subject per topic.
-
The difference between task, concept, and reference topics.
-
What a good task, concept, and reference topic looks like.
DITA Reference
169
Production Guide
Topic Elements
Use the generic topic structure for un-typed topics. While much of the DITA architecture is built on generic topics, it is generally better to use more specific information types (such as concept, task, or reference) when they are available. An example of an un-typed topic would be a collection of reusable content such as variables. See
Note:
Most of the topic elements listed here can be used in a task, concept, or reference topic.
•
<topic> is the top-level DITA element for a single-subject topic or article. Content-specific top-level DITA elements are <concept>, <task>, <reference>, and <glossary>.
•
<title> contains a heading or label for the main parts of a topic, including the topic as a whole, its sections and examples, and its labeled content such as figures and tables.
Beginning with DITA 1.1, this element can also be used to provide a title for a map.
•
<titlealts> (optional) occurs after the topic title. Two elements can be inserted as sub-elements: navigation title <navtitle> and search title <searchtitle>.
-
<navtitle> is a navigation title that can differ from the first level heading that shows in the main browser window. Use <navtitle> when the title of the topic is not appropriate in navigation panes or online content because it is too long.
-
<searchtitle> creates a title element at the top of the resulting HTML file. This title is normally used in search result summaries by some search engines, such as Eclipse
(
http://eclipse.org
). When not set, the title element defaults to the source topic title content (which might not be as well optimized for search summaries)
•
<abstract> occurs between the topic title and the topic body for the initial topic content. It can contain paragraph-level content and one or more <shortdesc> elements that provide link previews or summaries. This element cannot be overridden by maps, but the
<shortdesc> element contained within can be overridden to create link summaries or previews.
•
<shortdesc> occurs between the topic <title> and the topic <body> for the initial paragraph-like content of a topic. It can also be embedded in an abstract element. This tag represents the purpose or theme of the topic, and is intended to be used as a link preview and for searching. When used in a DITA map, the <shortdesc> of the <topicref> element can be used to override the <shortdesc> in the topic.
•
<body> is the container for the main content of a <topic>.
•
<section> represents an organizational division in a topic. Multiple sections within a single topic do not represent a hierarchy, but peer divisions of that topic. Sections cannot be nested. A section can have an optional title.
•
<example> is a section that contains examples that illustrate or support the current topic.
The <example> element has the same content model as <section>.
•
<related-links> contain related information links of a topic. This information is stored in a special section following the body of the topic. After a topic is processed into its final output form, the related links are usually displayed at the end of the topic, although some
Web-based help systems might display them in a separate navigation frame.
DITA Reference
170
Production Guide
Task Elements
Task topics answer How do I? questions, and have a well-defined structure that describes how to complete a procedure to accomplish a specific goal. Use the task topic to describe the steps of a particular task or to provide an overview of a higher-level task. The task topic includes sections for describing the context, prerequisites, actual steps, expected results, example, and expected next steps for a task.
•
<title> provides the topic or section title.
•
<shortdesc> introduces the task.
•
<steps>, <step>, <cmd> contain ordered steps for a task.
•
<steps-unordered> contains unordered steps for the entire procedure.
•
<context> Provides background information that users need to understand to do the task.
•
<substeps, <substep>, <cmd> contain the substeps for a step. One level of nesting only.
•
<info> provides additional information that users might need when they complete a step.
•
<stepresult> provides what happens when a step is completed. Use the <stepresult>.
Note:
For software documentation, you do not need to add “The XY window displays because users can see what windows open when they do the step.
•
<stepxmp> provides an example of what happens when a step is completed. <choices> and <choice> displays choices in a bulleted list instead of ordered steps.
•
<choices> and <choice> display choices in a bulleted list instead of ordered steps.
•
<choicetable> displays choices in a two-column table where you describe steps for each choice. Use the <choicetable> element for two-part items such as the name of an operating system and a corresponding file name or a bicycle model and its frame size.
•
<postreq> provides information about tasks that has to be done after the current task is done. <example> provides an example that illustrates or supports the task.
•
<result> provides the expected outcome when the task is done.
•
<example> shows examples of what the procedure might accomplish.
Figure 28. Sample task topic in WYSIWYG mode
DITA Reference
171
Production Guide
Figure 29. Sample task topic in markup mode
The XML markup for the sample task topic follows. DITA authoring tools provide a way to view the XML code, which can sometimes be an easier way to troubleshoot a syntax error.
<task xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="task-1" xsi:noNamespaceSchemaLocation="urn:oasis:names:tc:dita:xsd:task.xsd:1.1">
<title>Log In to the N150 Modem Router</title>
<shortdesc>Log in to the wireless modem router to view or change settings or to set up the wireless modem router.</shortdesc>
<taskbody>
<steps>
<step conref="Images/login.jpg">
DITA Reference
172
Production Guide
<cmd>Type <b>http://192.168.0.1</b> in the address field of your browser and press <b>Enter</b> to display the login window. You can also enter either of these addresses to access the wireless modem router:
<b>http://www.routerlogin</b>.net or
<b>http://www.routerlogin.com</b>.</cmd>
<stepxmp>
<image href="Images/login.jpg"/>
</stepxmp>
</step>
<step>
<cmd>When prompted, enter admin for the router user name and password for the router password, both in lowercase letters.</cmd>
<info>
<note>The router user name and password are probably different from the user name and password for logging in to your Internet connection.</note>
</info>
<stepresult>The router menus display where you can do things like change settings or add other devices to your network.</stepresult>
</step>
</steps>
</taskbody>
</task>
Concept Elements
DITA concept topics answer What is... questions. Use the concept topic to introduce background or overview information for tasks or reference topics. In a concept topic where other sections or examples are used, only other sections or examples are permitted as.
•
<title> provides the topic or section title.
•
<shortdesc> introduces the topic.
•
<conbody> contains more description of the concept where you can add sections, paragraphs, and other elements.
•
<section> contains a subsection that you can use to organize the conceptual information.
•
<sl> displays a list of short or simple items.
•
<ul> displays content as an unordered bulleted list.
•
<dl> displays a list of terms or short concepts and their definitions.
•
<image> provides a figure so that you can insert graphics.
•
<fig> provides a caption for an image.
•
<term> highlights new terms
DITA Reference
173
Production Guide
Figure 30. Sample concept topic in WYSIWYG mode
The XML markup for the sample concept:
<title>Box Contents</title><shortdesc>Make sure you have everything you need to cable your router.</shortdesc><conbody>
<p><ul>
<li>N150 Wireless ADSL2+ Modem Router DGN1000</li>
<li>AC power adapter (plug varies by region)</li>
<li>Category 5 (Cat 5) Ethernet cable</li>
<li>Telephone cable with RJ-11 connector</li>
<li>Microfilters and splitters (quantity and type vary by region)</li>
<li>Resource CD with NETGEAR Genie setup</li>
<li>Installation guide with cabling and router setup instructions</li>
</ul>If any of the parts are incorrect, missing, or damaged, contact your
NETGEAR dealer. Keep the carton, including the original packing materials, in case you need to return the product for repair. </p>
<image href="Images/DGN1000_contents.jpg"/>
<fig>
<title>Box Contents</title>
</fig>
DITA Reference
174
Production Guide
</conbody>
Reference Elements
Use the reference elements to describe regular features of sets of things, most commonly the commands in a programming language. However, this format is also suitable for recipes, bibliographies, catalogues, and similar collections of structured descriptive prose.
•
<title> provides the topic or section title.
•
<shortdesc> introduces the topic.
•
<refbody> contains the body of the topic.
•
<section> organizes content in a topic into sections.
•
<table> contains table content
•
<ul> displays content as an unordered bulleted list.
•
<dl> displays a list of terms or short concepts and their definitions.
•
<example> contains example content that explains or supports the topic.
•
<parml> displays parameters in a format similar to a definition list.
•
<properties> lists properties in a table by type, value, and description.
•
<simpletable> provides a table that does not require a title.
•
<refsyn> Contains syntax or signature content such as command-line utility calling syntax, an API signature, or a syntax or high-level structure diagram.
•
<properties> element for tables that describe types, values, and descriptions for each item.
DITA Reference
175
Production Guide
Figure 31. Sample reference topic in WYSIWYG mode (partial)
The XML markup for the sample reference topic (partial):
<title>Technical Specifications</title>
<shortdesc>Your router is manufactured to the following specifications.
This information can help you correctly set up and maintain your router</shortdesc>
<refbody>
<section>
<title>Network Protocol and Standards Compatibility</title>
<simpletable>
<sthead>
<stentry>Protocols</stentry>
<stentry>Description</stentry>
</sthead>
<strow>
<stentry>Data</stentry>
<stentry>TCP/IP, RIP-1, RIP-2, DHCP, PPPoE or PPPoA</stentry>
</strow>
<strow>
<stentry>Routing</stentry>
<stentry>RFC 1483 Bridged or Routed Ethernet, and RFC 1577
Classical IP over ATM.</stentry>
</strow>
DITA Reference
176
Production Guide
</simpletable>
</section>
........
</refbody>
</reference>
DITA Maps
DITA maps have many of the same common attributes as DITA content, but also have attributes to control the way relationships are interpreted for different output. Storing output information in the DITA map makes the topics completely reusable across multiple media.
DITA maps let you do the following:
•
Define an information architecture before, after, or during topic creation.
•
Provide an authoring interface for new and existing topics.
•
Define the topics to build for a particular output.
•
Define online navigation or table of contents for the topics in the map.
•
Define what topics to combine and nest for printing.
•
Define relationships among the topics in the DITA map. In the output, the relationships
become related links for the topics. See
on page 177 for more information.
Bookmaps
A bookmap is a type of DITA map that provides elements and attributes for creating PDF output in a book-style format. The format includes book title, front matter, chapters, appendices, back matter, and book metadata (author, copyright, book number).
A bookmap is nearly the same as a DITA map. So, if you need multiple output formats such as HTML, PDF, and eBook, it is better to use a DITA map. A DITA map is also lower maintenance for writers compared to a bookmap.
Note:
To set up a low-maintenance book structure with a DITA map, put the necessary book metadata in the topicmeta element. Then, add standard information such as copyright and year to the output by putting this information in your XSL transform. See
Metadata on page 181 for more information.
Topic Linking
In DITA linking helps people navigate from one topic to another. A well designed linking strategy creates a web of information that is easier to navigate and find information. There are the following types of links:
DITA Reference
177
Production Guide
Hierarchical links show the navigation of your information through nested topics. A list of related topics at the end of the topic gets created automatically when you generate output. A parent will always have links to its children and a child will always have a link to its parent.
Related links can be hard coded with the related-links element or soft coded in a relationship table. A relationship table is the preferred method because it is more flexible than hard coding links. WIth a relationship table, you create and maintain links in the DITA map rather than in the topics.
Each row in the table represents a relationship that is rendered as a link. Each cell represents participants in the relationship. When the relationship table is created, each topic reference in a cell links to the topic references in the other cells in the same row. For more information see
Linking DITA Topics Through Relationship Tables.
The following figure shows the code for an example relationship table. This is a DITA topic that includes a hierarchical link and a relationship table at the bottom when it is rendered.
Hierarchical Link
Relationship Table
Figure 32. Hierarchical and related links
Inline links are inserted in the topic text to connect users to related information. These links are handled with the xref element. It is best to limit cross-referencing because if you reuse a topic, you have to include all other topics that are within the cross-referencing scheme to avoid broken cross-references. The following is the XML for an example inline link.
<concept xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="concept-1"
DITA Reference
178
Production Guide
xsi:noNamespaceSchemaLocation="urn:oasis:names:tc:dita:xsd:concept.xsd:1.1">
<title>DGN1000 At-A-Glance</title>
<conbody>
<p>The <varname conref="variables.xml#topic-1/modem"/> provides you with an easy and secure way to set up a wireless home network with fast access to the Internet over a high-speed digital subscriber line (DSL). It has a built-in DSL modem, is compatible with all major DSL Internet service providers, lets you block unsafe Internet content and applications, and protects the devices (PCs, gaming consoles, and so on) that you connect to your home network.</p>
<p>See <xref href="RouterLogin.xml"/>
for information on logging into your <varname conref="variables.xml#topic-1/modem"/>. </p>
</conbody>
</concept>
Collection links create links among a group of nested topics. They also specify how links between parent, child, and sibling topics appear in the output. The collection-type attribute can be applied to topicref elements in a DITA map, topic-group elements in a relationship table, and columns in a relationship table.
Variables
In DITA, variables are implemented by containing the section of text to be reused in an inline element and reusing the inline element with a content reference. It's best to keep a collection of reusable pieces of information that can be shared across topics in a DITA topic that contains only variables.
Define a Variable

To define a variable:
1.
Create a variables topic with the generic topic type
2.
Add a p element to the variables topic.
3.
Inside the paragraph add an inline element such as ph, filepath, or varname.
4.
Set the id attribute of the inline element to the variable name.
5.
Set the value of the element to the variable value.
For example, the following are the definitions for the productname and modem variables.
Blue highlighting calls your attention to values you need to reference when you reuse the
<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
id="topic-1
" xsi:noNamespaceSchemaLocation="urn:oasis:names:tc:dita:xsd:topic.xsd:1.1">
<title>Variables</title>
<body>
DITA Reference
179
Production Guide
<p>
<varname id="productname">
N150 Wireless ADSL2+ Modem Router
ï€
DGN1000</varname></p>
<p><
varname id="modem">
modem router</varname></p>
</body>
</topic>
The phrase (<ph>) element is used to organize content for reuse or conditional processing
(for example, when part of a paragraph applies to a particular audience). It can be used by specializations of DITA to create semantic markup for content at the phrase level, which then allows (but does not require) specific processing or formatting.
The <filepath> element indicates the name and optionally the location of a referenced file by specifying the directory containing the file, and other directories that may precede it in the system hierarchy. This element is part of the DITA software domain, a special set of DITA elements designed to document software tasks, concepts and reference information.
The variable name (<varname>) element defines a variable that must be supplied to a software application. The variable name element is very similar to the variable (var) element, but variable name is used outside of syntax diagrams. This element is part of the DITA software domain, a special set of DITA elements designed to document software tasks, concepts and reference information.
Reference a Variable
Variables are reused by creating a content reference (conref) to the inline element that contains the variable text.
A conref, or content reference, is an attribute of an element within a topic or a map that pulls the content into the element from another element of the same type. Any topic and element with an ID can be reused by means of a conref. Conref can be displayed two ways: either resolved (as regular content) or as the path to the target element.
Local conrefs can link to:
•
Local elements
•
Local topics
External conrefs can link to:
•
External elements
•
External topics

To reference a variable:
1.
Place your cursor where you want the variable to be.
2.
Insert a varname element at that location.
3.
Apply a conref attribute to the varname element
The conref attribute has a target that is the name of the file and topic ID where the variable is defined, and the variable name in the form: flie.xml#topicID/variableName. The following is
DITA Reference
180
Production Guide
the XML that shows how to reuse the variables defined in
Blue highlighting calls your attention to values used when you defined the variables.
<varname conref="variables.xml
#topic-1
/
productname
"/>
<varname conref="variables.xml
#topic-1
/
modem
"/>
Figures and Callouts
The fig element can contain an image, an ordered list, a paragraph and a table. This provides the tools for building a set of labels, a legend, or multiple captions. An example of a definition list within a figure structure is:
<fig>
<title>Example of keyed callouts on an illustration</title>
<image href="../images/callout_key_ej25_turbo.jpg"
ï€ width="393px" height="322px"
<alt>Example of keyed callouts on an illustration</alt>
</image>
<dl>
<dlentry>
<dt>A</dt>
<dd>intercooler</dd>
</dlentry>
<dlentry>
</dlentry>
</dl>
</fig>
<dt>B</dt>
<dd>expansion tank</dd>
Metadata
Metadata is information about the content in your DITA topics and maps. When properly implemented, metadata can help writers create content that is targeted to specific audiences, products, versions, and so on to help users find the right information. In DITA there are many topics that have to be tagged with metadata so they can be correctly located and used.
You can use DITA metadata elements to do the following:
•
Include information to meet legal or company requirements
•
Improve content retrieval
•
Customize information for different audiences, versions, models, and so on
Metadata can help you customize delivery features such as dynamic publishing and faceted browsing. For example, you can set up a dynamic publishing mechanism so that users can
DITA Reference
181
Production Guide
select the types of content that they need based on categories (operating system, server type, etc.), model number, or size. Faceted browsing helps to narrow the number of topics that are relevant to a specific user by listing only the information that is relevant to their search.
Types of metadata:
•
Index entries
•
Conditional processing attributes
•
Topic metadata
•
DITA map metadata
•
Bookmap metadata
Note:
You can also create custom metadata for DITA maps and topics with the othermeta element.
DITA Reference
182
Production Guide
Index Entries
In additional to the normal use of an index, which is to locate information within a document, index entries can also be used as search terms for external web crawlers. Even if no one ever sees your index, the index entries can help users find your information.
You can place an index entry almost anywhere within a topic, but you should insert most of them in the keywords element of the prolog element. This ensures that the index entries for a topic are in the same location and that the terms can be best optimized for search engines.
Use the indexterm element to add index entries. Nested indexterm elements create primary and secondary index entries.
Use the index-see and index-see-also elements to create see and see also entries. Use the index-sort-as element to specify a different sorting phrase for an index entry.
Conditional Processing Attributes
Conditional processing attributes let you flag topics and elements to include or exclude content or flag content with a graphical icon to make scanning easier. You can also apply values to conditional processing attributes such as audience, product, platform, and revision to sort information along any of those lines.
Topic Metadata
Topic metadata is applied to the entire topic and contains information about the author, date created, and other internal, administrative information.
•
Writers can use the administrative information to maintain content over many years
•
Writers can use the topic metadata to locate content in a file management system
•
Users can use the topic metadata to filter content in a dynamic publishing or faceted browsing system
Topic metadata goes inside the prolog element for the topic. Docs groups should decide which metadata information to use and how to use it.
Here is a list of topic metadata that is valid inside the prolog element organized by the possible reason you would want to use it:
Reason
Legal
Maintenance
Types of Metadata Information Allowed in the
<prolog> Element
Copyright
ï€
Publisher
Dates
ï€
Revision information
ï€
Author
DITA Reference
183
Production Guide
Reason
Search
Index
ï€
(also useful for search)
Types of Metadata Information Allowed in the
<prolog> Element
Platform
ï€
Product
ï€
Permissions
ï€
Brand
ï€
Audience
ï€
Category
Keywords
Index terms
ï€
See index terms
ï€
See Also index terms
DITA Map Metadata
You can provide metadata for the topics included in a DITA map. There are advantages and disadvantages to applying metdata at the map level. Some people feel that applying metadata at the map level provides more reuse potential for the topics. Others feel that applying metadata at the topic level keeps the metadata closest to the content and allows writer to set it as they write.
If metadata is applied at the DITA map level, use the topicmeta element inside the topicref element.
Bookmap Metadata
Bookmap metadata is contined in the bookmap element. The bookmap element allows additional metadata over what is allowed in the topicmeta element.
Metadata Inheritance
Some metadata is inherited. Be aware that standard DITA processing happens from the top down. By default DITA map metadata combines with or overrides topic metadata. Inheritance can be a quick way to apply metadata to sets of topics in the same hierarchy. The disadvantage is that inherited metadata can be misappllied on the topics if it is not done carefully.
•
DITA map metadata: This metadata is applied to all topics inside the DITA map.
•
Parent topicref element: This metadata is applied to all child topics nested under the parent.
•
Topic metadata (child topicref element or prolog element): This metadata is applied to only that topic.
DITA Reference
184
Production Guide
Taxonomy
A taxonomy is a hierarchical structure that organizes subjects and controls the vocabulary that can be used to describe those subjects. Taxonomies let organizations create and centrally manage important terms that can be applied to topics and maps as metadata. When metadata and taxonomy information are applied to topics and maps, search applications can access the metadata to retrieve content. Search engines can also use the taxonomy to organize search results in meaningful ways and to suggest related searches.
A taxonomy is a DITA map specialization. Specialization is the process by which new designs are created based off of existing designs. Specialization allows new kinds of content to be processed with existing processing rules. See
DITA Specialization
for more information.
The taxonomy is created in a specialized DITA map by adding topicref elements to the map in a hierarchy. Each topicref element points to a topic that describes the subject of that node of the taxonomy. The description declares the content’s subject matter in a way that a semantic processor can understand.
Simple Knowledge Organization System (SKOS) is a standard for describing the subject matter of content. SKOS lets you define the subjects for a particular subject matter area and classify each piece of content to indicate its subject. The basic steps to define subjects and classify content are as follows:
•
Define the subjects
•
Organize the subjects
•
Classify the content

To define the subjects:
Create a DITA topic that identifies an aspect of the subject matter of the content. This topic is typically a concept topic. The DITA topic specifies the subjects with a subjectxxx element to specify the following kinds of information: default labels that include synonyms and denotative images, and notes on the definition and on the scope of coverage for the subject.
<concept id="configuring">
<title>Configuring</title>
<shortdesc>You configure components to set up or refine a solution.</shortdesc>
<conbody>
<p>You don't have to get the best configuration the first time....</p>
<subjectDetail>
<subjectLabels>
<altLabel>Setting up</altLabel>
</subjectLabels>
<scopeNote>Administrative tasks performed after installation</scopeNote>
</subjectDetail>
</conbody>
</concept>
DITA Reference
185
Production Guide

To organize the subjects:
Create a subject scheme. A subjectScheme is a specialized DITA map that defines a collection of controlled values rather than a collection of topics. You can have multiple schemes for the same subjects. For instance, different audiences might be interested in a different subset of the taxonomy.
Note:
If you do not organize subjects into a hierarchical taxonomy or otherwise express relationships between subjects, you do not have to create a scheme.
You can still classify content topics without a scheme.
The following is an example of a subject scheme that identifies Installing and Configuring as
Task subjects and Resource utilization and Security as Concerns:
<subjectScheme title="Sampletaxonomy" id="taxonomyScheme">
<subjectdef href="task.dita" navtitle="Task">
<subjectdef href="installing.dita" navtitle="Installing"/>
<subjectdef href="configuring.dita" navtitle="Configuring"/>
...
<subjectdef href="concern.dita" navtitle="Concern">
<subjectdef href="utilization.dita" navtitle="Resource utilization"/>
<subjectdef href="security.dita" navtitle="Security"/>
...

To classify content:
Inside the topicref element for a topic or map that refers to the classified content, nest a topicsubject element that identifies the subjects of the content. The subjectref element identifies a subject with an href or a keyref attribute. See
Subject classification with DITA and
SKOS
for more information. See also
XML Topic Maps (XTM) 1.0.
<topicref href="websecure.dita">
<topicsubject>
<subjectref href="webserver.dita"/>
<subjectref href="security.dita"/>
</topicsubject>
<topicref href="https_protocol.dita"/>
</topicref>
<topicref href="loginsetup.dita" collection-type="sequence">
<topicsubject>
<subjectref href="configuring.dita"/>
<subjectref href="webserver.dita"/>
<subjectref href="security.dita"/>
</topicsubject>
<topicref href="editinguserdef.dita"/>
</topicref>
DITA Reference
186
Index
Numerics
4Backup folder
A
accessibility check
errors
font problems
guidelines
Acrobat Distiller
Add/Setup GenFiles
Adobe Illustrator, color modes
Agile
alternate text
Americans with Disabilities Act (ADA)
anchored frames
appendix tags
approval, document
archiving docs
electronic documents
printed documents
artwork, in Agile
B
bar codes
bar codes, QR codes
Beta documents
black and white printing
blank pages, removing
book files
borders
business units
C
calculate doc due dates
calculate docs due dates
callout text
callouts (DITA)
carrier products
187
CDs
certification documents
change bars
checklists lead writers
writers
Citrix web interface access to V drive
clean up converted files
Cleanup Catalogs
clearing laptop memory
CLI manual
CMYK color mode
CMYK colors
Collection links (DITA)
color modes
CMYK
RGB
color printing
combining PDFs
comments
compliance
Compressed Object Streams warning
concept elements (DITA)
content reuse, and DITA
contract writer document hand-off
lead writer duties
contract writer role
convert old docs
crop marks
cross reference tool
cross-references
D
Darwin Information Typing Architecture (DITA) content reuse
defined
described
elements
figures and callouts
linking
localization
metadata
metadata inheritance
printed documents
taxonomy
tools
training for
transitioning to
variables
designer role
desk phones
developmental reviews
disconnected pages
distribution lists, email
distribution, review
DITA maps
doc reviews
docs server
,
document preparation
document types
Beta
certification
documentation request
documentation set, determining
documents approving
archiving
beta
in Agile
localized
due dates, doc
E
editing guidelines
editor role
electronic documents, archiving
elements concept
reference
task
topic
elements, DITA
email distribution lists
engineering teams
exporting graphics
external PDFs, linking to
F
fast track review
Figures (DITA)
fiile purposes
Production Guide
file naming
final doc review
first doc review
fonts
clean up
Preflight error
FrameMaker blank pages
disconnected pages
fonts
links
metadata
PDF generation
Save as PDF command
screen shots
templates
vardefs file
warnings, turning off
frontmat
full accessibility check
G
geardog
4Backup
FTP site
geardog, accessing
general styles
giftbox
graphics
graphics tools
H
hardware installation guide
Hierarchical links (DITA)
Home business unit
I
illustrations
illustrator role
importing screen captures
incorporating review comments
index tags
install guide
PDFs
place mat
print spec
install guides
editing
file naming
188
L
language options, setting on PDF
laptop memory, clearing
large PDFs, sending for review
lead writer checklist
part numbers
lead writer role
legal team
linking to external PDFs
links
links to Internet resources
localition
DITA
localization about
calculating doc due dates
localization team
localization, and DITA
M
manager role
marketing collateral
marketing team
master pages
meetings, desktop sharing for
memory, laptop, clearing
menu tools
metadata (DITA)
metadata inheritance (DITA)
metadata, PDFs
model numbers
N
naming files
NetgearTools folder, create
NetgearUtils
Numbering and Update Book
O
online documents, color modes
ordering software
Other Features section
P
packaging team
Production Guide
part numbers
CDs
certification documents
Part#TBD
PDFs archibing
see tagged PDFs
PDFs, link to external
phones
photos, product
place mat, install guide
platform products
Preflighr
Preflight
Print Book command
print spec about
printer contacts
printed documents, and DITA
printed documents, archiving
printed documents, color modes
printer contacts
printing, color and BW
product design team
product names,
product photos
production person role
Q
QR codes
quick install guide
quick install guides
R
Read Out Loud
reconversion
reference elements (DITA)
reference pages
reflow document
Related links (DITA)
release approval
RemapConfigFile
remote access to V drive
reviewers approvals
comment acceptance
response
who reviews what
reviews
189
cycles
PDFs
reviewsl
RGB color mode
S
Save as PDF command
scaling images
scheduling doc reviews
screen shots about
combining
dedicated laptop
importing
preparing
Print Screen
RoboScreenCapture
WinTV
search, tagged PDFs
Section 508
service provider business unit
Set PDF Metadata
setup manual
about
product illustration
setup manuals editing
SMB business unit
software administration manual
software, ordering, CDW for software orders
SPBU
starting a document
storage business unit
support, links to
T
table of contents tags
tag styles
tagged PDFs
accessibility check
accessibility errors
Acrobat Distiller
alternate text
bar codes
combining
creating
crop marks
font problems
full accessibility check
generating
install guides
Production Guide
language options
large
metadata
Preflight
print book command
Read Out Loud
reflow document
reviews
Save as PDF command
search engines
Section 508 of ADA
structure
tagged
task elements (DITA)
taxonomy (DITA)
technical doc review
technical publications deliverables
job roles
technical reviews
technical support team
telephones
template conversion tools
templates
TOC
tools
topic elements (DITA)
topics (DITA) linking
trademarks
U
URLs
URLs in docs
usability team
user manual about
product illustration
user manuals
file naming
V
V drive
AgileDropFolder
current projects
read-only access
VPN access
vardefs
vardefs file
variables
variables (DITA)
190
Production Guide
variables in book
variables tool
versions, product
virus scans
VPN access to V drive
W
warning
warnings, turning off in FrameMaker
Waste Electrical and Electronic Equipment (WEEE)
web search
WEE symbol and text
WinTV screen shots
writer role
writers, checklist
Z
zip files
191
advertisement
Key Features
- Writing and updating documentation
- Creating departmental templates and designs
- Laying out graphics and creating illustrations
- Editing customer-facing materials, such as GUI text and help files
- Managing document scheduling and production for product releases across all BU’s
- Building the CD with all product-specific information and deliverables
