Modular documentationin Structured FrameMaker
Jang F.M. Graat
JANG Communication
Who’s talking ?
Jang F.M. Graat
Physics, Psychology, Philosophy
20+ years Tech Writer, Trainer, Consultant
15+ years company JANG Communication
Self-taught FM expert
Agenda for this tutorial
Step 1: Defining your modular structure
Step 2: Defining the top-level elements
Step 3: Defining the layout properties
Step 4: Using text insets to reuse modules
Step 5: Creating your own CMS
Agenda for this tutorial
Step 6: Handling cross-references in reuse
modules
Step 7: Allowing variability in reuse modules
Step 8: Creating books from reuse modules
Step 9: Publishing to various layouts
Wrap-up
Step 1: Defining your modular structure
Modular design: top-down
Book
Chapter Chapter
Section
TopicTopicTopic
Section Section
TOC Index
Modular design: bottom-up
Book
Chapter Chapter
Section
TopicTopicTopic
Section Section
TOC Index
Modules: reusability
Modules Maps Pubs
Granularity of modules
Number of modules
Generic vs. specific
Impact on reusability
How much chaos can you manage ?
Multiple layers of (nested) modules
Topic-based writing
Answer one question
“What is this for ?”
“How does it work ?”
“How do I do this ?”
“What are my options ?”
“What went wrong ?”
All other info
Related links
Writing for reusability
Generic topics
Less is more
Clear structure
Rigid structure
Generic vs. specific
Separate variability
Use conditional text ?
Nesting of modules
Allow modules to contain other modules
Module used at various levels in publications
Formatting issues
Levels of titles
Font families, sizes
Indentation, tabs
Naming conventions
Strict naming rules
Recognizable
Unique names
Prefixed types
task-RemoveBoard
ref-FileSaveOptions
concept-Mod5402
t-5402-Adjust
Finding modules
Meaningful titles
Valid for which part ?
Include version info ?
Attributes of main module elements
Directory structure
Excel sheet to keep track of everything
Document Type Definition
Chapter
Book
Title
Section
Title
Body
Para
Section
Defines valid structure
<!DOCTYPE MyBook [
<!ELEMENT Book (Chapter+)><!ELEMENT Chapter (Title,Section+)><!ELEMENT Section (Title,Body?,Section*)><!ELEMENT Body (Para+)><!ELEMENT Title (#PCDATA)><!ELEMENT Para (#PCDATA)>
<!ATTLIST Author CDATA #REQUIRED><!ATTLIST Editor CDATA #IMPLIED><!ATTLIST Date CDATA #IMPLIED><!ATTLIST Version CDATA #IMPLIED>
]>
EDD: Element Definition Doc
Element definitions
Unique name
General rule: structure
Attributes
Formatting rules
DTD + formatting
Part of every FM file
Imported from EDD file
Modular EDD - step 1
EDD Version is 8.0
Element (Container): Book General rule: Chapter+
Element (Container): Chapter General rule: Title, Section+
Element (Container): Section General rule: Title, Body?, Section*
Element (Container): Body General rule: Para+
Element (Container): Para General rule: <TEXT>
Element (Container): Title General rule: <TEXTONLY>
Chapter
Book
Title
Section
Title
Body
Para
Section
Step 2: Defining thehighest-level elements
Documentation systems
Book
Content
Chapter
Flow
Fm
Dita
Book
Content
Ditamap
File
Highest-level elements
Available as root ina FrameMaker file
Element (Container): Book General rule: Chapter+ Valid as the highest-level element.
Element (Container): Chapter General rule: Title, Section+ Valid as the highest-level element.
Element (Container): Section General rule: Introduction, SubSection+ Valid as the highest-level element.
Element (Container): Introduction General rule: (Par | Figure)+
Element (Container): SubSection General rule: Title, (Par | Figure)+ Valid as the highest-level element.
Why is this important ?
Modular documents
Each file = one topic
Validation of structure
Separate handling(review, translation)
Inclusion via linking
Reused via text insets
Include entire flow
Starts at root element
File: module1
Title
Section
Figure
ImageFrame
File: chapterA
Title
Chapter
File: module1File: module4
Granularity of modules
Number of modules
Generic vs. specific
Impact on reusability
How much chaos can you manage ?
Multiple layers of (nested) modules
Modular EDD - step 2
EDD Version is 8.0
Element (Container): Book General rule: Chapter+ Valid as the highest-level element.
Element (Container): Chapter General rule: Title, Section+ Valid as the highest-level element.
Element (Container): Section General rule: Title, Body?, Section*Valid as the highest-level element.
Element (Container): Body General rule: Para+
Element (Container): Para General rule: <TEXT>
Element (Container): Title General rule: <TEXTONLY>
Chapter
Book
Title
Section
Title
Body
Para
Section
Step 3: Defining the layout properties
Defining layout properties
Layout is for users
Company style guide
Rigid system
No exceptions !!!
No “tweaking” !!!
Nesting of modules
Various publications
Direct formatting in EDD
Element (Container): Body General rule: <TEXT> Text format rules In all contexts. Default font properties Family: Arial CE Size: 10pt Basic properties Paragraph spacing Space above: 2pt Space below: 10pt Line spacing Height: 12pt Tab Stops Tab stop position: 11.0mm Tab stop position: 18.0mm Tab stop position: 21.0mm
All formatting options
Basic properties
Font properties
Numbering properties
Pagination properties
Advanced properties
Everything available in paragraph designer
Using format control lists
Advantages
Usually gathered in one section of the EDD
Reuse of the same fclfor multiple elements
Easier to manage
Disadvantages
Still part of the EDD
Not all options available
Formatting outside EDD
Change formatting without editing EDD
Paragraph format tags
Separate style guide
Advantages:
Accessible formatting
Easier bookmarking
Multiple style guides
EDDStyle guide
Document
FirstPar
Title
BulletList
Structure Formatting
Tags
ListItem
Paragraph format tags
Unique format tags
Choose intelligent names
Importing EDD
Create formats on input
Paragraph tags added
Formatting in template
Paragraph designer
Always use “Update all”
EDDStyle guide
Using context rules
All Contexts rule
Context rule
Parent element
Nesting of elements
Choice of elements
First, last, after
Order of execution
First match stops search
Element (Container): Body General rule: <TEXT> Text format rules 1. In all contexts. Use paragraph format: Body
Element (Container): Title General rule: <TEXT> Text format rules
1. If context is: ChapterUse paragraph format: ChapTitle
Else, if context is: AppendixUse paragraph format: AppTitle
Else, if context is: Section < ChapterUse paragraph format: SecTitle
Else, if context is: Section {after Title}Use paragraph format: SubSecTitle
ElseUse paragraph format: FigTitle
Modular EDD - step 3
Title element
Section title dependson level of nesting
Level rule in EDD
Paragraph format tags
Required heading level
Note: no exceptions !
Nested context rule
Step 4: Using text insetsto reuse modules
FrameMaker text insets
Import entire flow
Disadvantages
Inset source required
No search mechanism
No previewing
No check on structure
West Street Consulting
FrameMaker ACE Russ Ward
Full-time tech writer + part-time software developer
Website: www.weststreetconsulting.com
Extremely useful plug-ins for FrameMaker
Xref Wizard ( $ 35 per seat )
FrameSLT ( $ 100 per seat )
InsetPlus ( free )
ABCM ( free )
InsetPlus
Element-level linking
Advantages
Any element in file
User-friendly interface
Search & preview
Check on validity
Updating quick & easy
Tracking of usage
InsetPlus linking method
Element attributes
Source: Unique ID
Target: conref
Inserting & updating
Insert empty element
Link to source element
Update indivual inset
Update all insets in file
InsetPlus: further options
Tracking information
Where is source used ?
Updating all references
Linking options
Editing conref attribute
No source required yet
Automated creation ofbooks in XML processor
Modular EDD - step 4Element (Container): Book General rule: Chapter+ Valid as the highest-level element.
Element (Container): Chapter General rule: Title, Section+ Valid as the highest-level element.
Element (Container): Section General rule: Title, Body?, Section* Valid as the highest-level element.
Attribute list 1. Name: id UniqueIDOptional 2. Name: conref StringOptional
Element (Container): Body General rule: Para+ Format rules for the first paragraph in element1. In all contexts
Pagination propertiesKeep with previous: Yes
Step 5: Creatingyour own CMS
Content Management
Keep track of stuff
Storing modules
Searching modules
Validity for publications
Review & translation
Database needed ?
No magic involved
Manage the chaos
Content Management
Finding content
Clear structure
Strict naming
Without a CMS ?
Store in repositories
Restrict modularity
Use nested modules
Document validity info
Repository files
Reusable elements
Wrapper with info
Enable search & checks
Printable as catalog
Bundle reuse modules
Machine section
Software section
Clear subdivision
Organize repository files
Collect in book
Printing full catalog
Easier updating
Easier to manage
Division of modules
One file per assembly ?
One file per topic type ?
One file per product ?
Modular EDD - step 5
Same EDD in all files
Guarantee compatibility
Sections in EDD
Formatting in EDD ?
Special info added:
Module identifier
Validity and version info
Optional comment
Element (Container): ReuseModule General rule: ModuleID, Comment?, Section Attribute list
1. Name: Author String Required2. Name: Version Integer Required3. Name: Revision Integer Required4. Name: Validity String Required
Element (Container): ModuleID General rule: <TEXTONLY> Prefix rules1. In all contexts
Prefix: Identifier: Suffix rules
1. In all contextsSuffix: \nValid for: <$attribute[Validity:ReuseModule]> \nVersion:
<$attribute[Version:ReuseModule]>.<$attribute[Revision:ResudeModule]>\n
Step 6: Handling Xrefsin reuse modules
Xrefs in FrameMaker
Allowing Xrefs
Marker attribute in allreferrable elements
CrossReference element with target attribute
Both attributes optional
Creating Xrefs
Enter CrossRef element
Link to available marker
Xrefs in FrameMaker
Xrefs to other files
Source file required
Source file changed !
Prepare for Xrefs
Manually define marker
FM attribute editor
Use unique names
Xrefs in FrameMaker
Updating Xrefs
Source files required
Xref to inset text
Xref to inset source,not to inset reference
Marker available,but not recognized
Manual relinkingSee X. X
See X. X
Book
XRef Wizard
Attribute-based linking
Unique IDs targeted
No file names used
Advantages
No file-dependence
Works with text insets
Updating quick & easy
Reports with links
XRef Wizard
Updating Xrefs
Book-level process
Only files in book
Xref to inset text
Xref defined in attributeindependent of filename
Marker recognized
Automatic relinking
See X. X
See X. X
Book
XRef Wizard
Book level
Resolves all Xrefs
Reports conflicts
Multiple targets
Choice of candidates
Allows jumping into
Fast and easy
Update book after this
Modular EDD - step 6
Element (Container): Para General rule: (<TEXT> | CrossRef )*
Element (CrossReference): CrossRef Attribute list 1. Name: XRefTarget ID Reference Optional
Element (Container): Title General rule: <TEXTONLY> Attribute list 1. Name: XRefMarker Unique ID Optional
Step 7: Allowing variability
in reuse modules
Variable info: FM variables
Special -> Variables
Defined per file
Import to each fileafter changing value
Use in text insets
Take value from file that includes the text inset
Does not export to XML
Variables in the EDD
Define element
Attribute determines which variable is used
Empty element text
Prefix receives valuefrom Book attributes
Edit variables
Edit Book attributes
Update book
Element (Container): BookVar General rule: <EMPTY> Attribute list
1. Name: Variable Choice Required Choices: Machine, Company,
Publisher, PubYear Text format rules In all contexts.
Text range. Prefix rules If context is: [Variable=”Machine”]
Prefix: <$attribute[Machine: Book]> Else, if context is: [Variable=”Company”]
Prefix: <$attribute[Company: Book]> Else, if context is: [Variable=”Publisher”]
Prefix: <$attribute[Publisher: Book]> Else, if context is: [Variable=”PubYear”]
Prefix: <$attribute[PubYear: Book]>
Variables in the EDD
Allow element
Part of General rule
Insert variable
Like all other elements
Only where allowed
Choose attribute valuefrom drop-down list
Update book !
Element (Container): Para General rule: ( <TEXT> | CrossRef | BookVar )*
Conditional text: FM method
Condition tags
Defined per document
Applied per text section
Works with text insets
Hide / show text
Set hide / show options
Boolean expression
All text remains in files
ABCM
Attribute-based
Define attributes in EDD
Any applicable element
Includes children
Condition schemes
Define schemes once
Color, filter, validate
Attribute-based conditions
Defined in EDD
Attributes applied toall useful elements
Define attributes once
Copy-paste attributes to all applicable elements
Conditions applicable only to elements
Element (Container): Section General rule: Title, Body?, Section* Attribute list 1. Name: id Unique ID Optional 2. Name: conref String Optional 3. Name: Version Choice Optional Choices: VersionA, VersionB, VersionC 4. Name: Product Strings Optional
Element (Container): Para General rule: (<TEXT> | CrossRef | BookVar )* Attribute list 1. Name: Version Choice Optional Choices: VersionA, VersionB, VersionC 2. Name: Product Strings Optional
ABCM schemes
Library of schemes
Coloring schemes
Filtering schemes
Validation schemes
Attribute-based
Match values
Combined matches
Execute rule
Coloring source files
Coloring scheme
Define color options
Define matching rules
Store coloring scheme
Applying a scheme
ABCM > Coloring > Color ...
Choose a coloring scheme
Apply the scheme
Filtering source files
Filtering scheme
Define matching rules
Store filtering scheme
Applying a scheme
ABCM > Filtering > Filter ...
Choose a filtering scheme
Choose destination options
Apply the scheme
Filtering books
Master
Product A
Product B
Product ADEU
Product BNLD
Modular EDD - step 7
Element (Container): ParaGeneral rule: (<TEXT> | CrossRef | BookVar )*Attribute list
1. Name: VersionChoice OptionalChoices: VersionA, VersionB, VersionC
2. Name: Product Strings Optional
Element (Container): BookVarGeneral rule: <EMPTY>Attribute list
1. Name: Variable Choice Required Choices: Machine, Company,
Publisher, PubYearText format rules
In all contexts.Text range.
Prefix rulesIf context is: [Variable=”Machine”]
Prefix: <$attribute[Machine: Book]>Else, if context is: [Variable=”Company”]
Prefix: <$attribute[Company: Book]>
Step 8: Creating booksfrom reuse modules
Limiting chaos
Library of subtopics
Standard warnings
Standard steps
Consistent topics
Follow machine design
Follow main tasks
Create topic templates
Consistent metadata
Consistent topics
Machine modules
Functional description
Operating
Maintaining, cleaning
Testing, adjusting
Troubleshooting
Removing, Mounting
Replacing parts
Consistent topics
Describe all buttons
Follow GUI design
One topic per screen
Describe procedures
Start-of-day
Normal operation
Maintenance
End-of-day
Possible subtopics
Notes, warnings
Procedure steps
Images + poslists
Button descriptions
Parameter descriptions
Examples
Specifications
Trade-off
Subtopics
Create more modules
Keeping track of usage
Complex dependencies
Conditional text
Create complex modules
Change one, change all
Copies after filtering
Publishing books
Order of final steps
Update all insets
Resolve all XRefs
Update book
Save book as PDF
One book per product
Back-up published book
Include all chapters
Keeping track
Excel workbook
Available topics
Versions, revisions
Status and planning
Available translations
Usage information
Manually in Excel
Via InsetPlus reports
Step 9: Publishingto various layouts
Formatting outside EDD
Change formatting without editing EDD
Paragraph format tags
Separate style guide
Advantages:
Accessible formatting
Easier bookmarking
Multiple style guides
EDDStyle guide
Document
FirstPar
Title
BulletList
Structure Formatting
Tags
ListItem
Import style guide formats
Page layouts
Page setup, sizes
Fixed elements, flows
Reference pages
Repository for icons
Paragraph formats
Character formats
Using various templates
Same style tags
Copy template
Change page layout
Change para formats
Change char formats
Include all tags
Add fixed elements
Standard master pages
Multiple style guides
Modular documentation
Writing topics
Assembling books
Updating Xrefs
Filtering books
Applying layouts
Publishing books
Questions ?
More info & materials: send e-mail to [email protected]