If DITA is too technical and a CMS is too costly, it is still possible to create modular documentation and reuse your content in as many publications as possible. This 2-hour tutorial presented at tcWorld 2009 shows how to create the required EDD in Structured FrameMaker.

1. Modular documentation
in Structured FrameMaker
Jang F.M. Graat
JANG Communication

2. Who’s talking ?
Jang F.M. Graat
Physics, Psychology,
Philosophy
20+ years Tech
Writer, Trainer, Consul
tant
15+ years company
JANG Communication
Self-taught FM expert

3. 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

4. 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

5. Step 1: Defining your
modular structure

6. Modular design: top-down
Book
TOC Chapter Chapter Index
Section Section Section
Topic Topic Topic

7. Modular design: bottom-up
Book
TOC Chapter Chapter Index
Section Section Section
Topic Topic Topic

8. Modules: reusability
Modules Maps Pubs

9. Granularity of modules
Number of modules
Generic vs. specific
Impact on reusability
How much chaos
can you manage ?
Multiple layers of
(nested) modules

10. 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

11. Writing for reusability
Generic topics
Less is more
Clear structure
Rigid structure
Generic vs. specific
Separate variability
Use conditional text ?

12. 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

13. Naming conventions
Strict naming rules
Recognizable
Unique names
Prefixed types
task-RemoveBoard
ref-FileSaveOptions
concept-Mod5402
t-5402-Adjust

14. 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

15. Document Type Definition
Defines valid structure
Book <!DOCTYPE MyBook [
Chapter <!ELEMENT Book (Chapter+)>
<!ELEMENT Chapter (Title,Section+)>
Title <!ELEMENT Section (Title,Body?,Section*)>
<!ELEMENT Body (Para+)>
<!ELEMENT Title (#PCDATA)>
Section <!ELEMENT Para (#PCDATA)>
Title <!ATTLIST Author CDATA #REQUIRED>
<!ATTLIST Editor CDATA #IMPLIED>
Body <!ATTLIST Date CDATA #IMPLIED>
<!ATTLIST Version CDATA #IMPLIED>
Para ]>
Section

16. 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

17. Modular EDD - step 1
EDD Version is 8.0
Book
Element (Container): Book
Chapter General rule: Chapter+
Element (Container): Chapter
Title General rule: Title, Section+
Element (Container): Section
Section General rule: Title, Body?, Section*
Title Element (Container): Body
General rule: Para+
Body Element (Container): Para
General rule: <TEXT>
Para
Element (Container): Title
General rule: <TEXTONLY>
Section

18. Step 2: Defining the
highest-level elements

19. Documentation systems
Book Book
Fm
Chapter Ditamap
Flow File
Content Content Dita

20. Highest-level elements
Element (Container): Book
Available as root in General rule: Chapter+
Valid as the highest-level element.
a FrameMaker file
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.

21. Why is this important ?
Modular documents File: chapterA
Each file = one topic Chapter
Title
Validation of structure
File: module1
Separate handling File: module4
(review, translation)
Inclusion via linking File: module1
Section
Reused via text insets
Title
Include entire flow Figure
Starts at root element ImageFrame

22. Granularity of modules
Number of modules
Generic vs. specific
Impact on reusability
How much chaos
can you manage ?
Multiple layers of
(nested) modules

23. Modular EDD - step 2
EDD Version is 8.0
Book Element (Container): Book
General rule: Chapter+
Chapter Valid as the highest-level element.
Element (Container): Chapter
Title General rule: Title, Section+
Valid as the highest-level element.
Section Element (Container): Section
General rule: Title, Body?, Section*
Title Valid as the highest-level element.
Body Element (Container): Body
General rule: Para+
Para Element (Container): Para
General rule: <TEXT>
Section Element (Container): Title
General rule: <TEXTONLY>

24. Step 3: Defining the
layout properties

25. Defining layout properties
Layout is for users
Company style guide
Rigid system
No exceptions !!!
No “tweaking” !!!
Nesting of modules
Various publications

26. Direct formatting in EDD
All formatting options
Element (Container): Body
General rule: <TEXT>
Basic properties Text format rules
In all contexts.
Font properties Default font properties
Family: Arial CE
Size: 10pt
Numbering properties Basic properties
Paragraph spacing
Pagination properties Space above: 2pt
Space below: 10pt
Line spacing
Advanced properties Height: 12pt
Tab Stops
Everything available in Tab stop position: 11.0mm
Tab stop position: 18.0mm
paragraph designer Tab stop position: 21.0mm

27. Using format control lists
Advantages
Usually gathered in one
section of the EDD
Reuse of the same fcl
for multiple elements
Easier to manage
Disadvantages
Still part of the EDD
Not all options available

28. Formatting outside EDD
Change formatting Style
without editing EDD EDD Tags
guide
Paragraph format tags
Structure Formatting
Separate style guide
Advantages: Document
Title
Accessible formatting
FirstPar
Easier bookmarking BulletList
Multiple style guides ListItem

29. Paragraph format tags
Unique format tags Style
EDD
Choose intelligent guide
names
Importing EDD
Create formats on input
Paragraph tags added
Formatting in template
Paragraph designer
Always use “Update all”

30. Using context rules
All Contexts rule Element (Container): Body
General rule: <TEXT>
Text format rules
Context rule 1. In all contexts.
Use paragraph format: Body
Parent element Element (Container): Title
General rule: <TEXT>
Text format rules
Nesting of elements 1. If context is: Chapter
Use paragraph format: ChapTitle
Choice of elements Else, if context is: Appendix
Use paragraph format: AppTitle
First, last, after Else, if context is: Section < Chapter
Use paragraph format: SecTitle
Else, if context is: Section {after Title}
Order of execution Else
Use paragraph format: SubSecTitle
Use paragraph format: FigTitle
First match stops search

31. Modular EDD - step 3
Title element
Section title depends
on level of nesting
Level rule in EDD
Paragraph format tags
Required heading level
Note: no exceptions !
Nested context rule

32. Step 4: Using text insets
to reuse modules

33. FrameMaker text insets
Import entire flow
Disadvantages
Inset source required
No search mechanism
No previewing
No check on structure

34. 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 )

35. InsetPlus
Element-level linking
Advantages
Any element in file
User-friendly interface
Search & preview
Check on validity
Updating quick & easy
Tracking of usage

36. 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

37. InsetPlus: further options
Tracking information
Where is source used ?
Updating all references
Linking options
Editing conref attribute
No source required yet
Automated creation of
books in XML processor

38. Modular EDD - step 4
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.
Attribute list
1. Name:id UniqueID Optional
2. Name: conref String Optional
Element (Container): Body
General rule: Para+
Format rules for the first paragraph in element
1. In all contexts
Pagination properties
Keep with previous:Yes

39. Step 5: Creating
your own CMS

40. Content Management
Keep track of stuff
Storing modules
Searching modules
Validity for publications
Review & translation
Database needed ?
No magic involved
Manage the chaos

41. Content Management
Finding content
Clear structure
Strict naming
Without a CMS ?
Store in repositories
Restrict modularity
Use nested modules
Document validity info

42. Repository files
Reusable elements
Wrapper with info
Enable search & checks
Printable as catalog
Bundle reuse modules
Machine section
Software section
Clear subdivision

43. 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 ?

44. Modular EDD - step 5
Same EDD in all files Element (Container): ReuseModule
General rule: ModuleID, Comment?, Section
Attribute list
Guarantee compatibility 1. Name: Author String Required
2. Name: Version Integer Required
3. Name: Revision Integer Required
Sections in EDD 4. Name: Validity String Required
Formatting in EDD ? Element (Container): ModuleID
General rule: <TEXTONLY>
Prefix rules
Special info added: 1. In all contexts
Prefix: Identifier:
Module identifier Suffix rules
1. In all contexts
Suffix: nValid for:
Validity and version info <$attribute[Validity:ReuseModule]>
nVersion:
Optional comment <$attribute[Version:ReuseModule]>.
<$attribute[Revision:ResudeModule]>n

45. Step 6: Handling Xrefs
in reuse modules

46. Xrefs in FrameMaker
Allowing Xrefs
Marker attribute in all
referrable elements
CrossReference
element with target
attribute
Both attributes optional
Creating Xrefs
Enter CrossRef element
Link to available marker

47. 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

48. Xrefs in FrameMaker
Updating Xrefs
Book
Source files required
Xref to inset text
Xref to inset source,
See X. X
not to inset reference
Marker available,
but not recognized
Manual relinking
See X. X

49. 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

50. XRef Wizard
Updating Xrefs
Book
Book-level process
Only files in book
Xref to inset text
See X. X
Xref defined in attribute
independent of filename
Marker recognized
Automatic relinking See X. X

51. XRef Wizard
Book level
Resolves all Xrefs
Reports conflicts
Multiple targets
Choice of candidates
Allows jumping into
Fast and easy
Update book after this

52. 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

53. Step 7: Allowing variability
in reuse modules

54. Variable info: FM variables
Special -> Variables
Defined per file
Import to each file
after changing value
Use in text insets
Take value from file that
includes the text inset
Does not export to XML

55. Variables in the EDD
Define element Element (Container): BookVar
General rule: <EMPTY>
Attribute list
Attribute determines 1. Name: Variable Choice Required
which variable is used Choices: Machine, Company,
Publisher, PubYear
Text format rules
Empty element text In all contexts.
Text range.
Prefix receives value Prefix rules
If context is: [Variable=”Machine”]
from Book attributes Prefix: <$attribute[Machine: Book]>
Else, if context is: [Variable=”Company”]
Prefix: <$attribute[Company: Book]>
Edit variables Else, if context is: [Variable=”Publisher”]
Prefix: <$attribute[Publisher: Book]>
Else, if context is: [Variable=”PubYear”]
Edit Book attributes Prefix: <$attribute[PubYear: Book]>
Update book

56. Variables in the EDD
Allow element Element (Container): Para
General rule: ( <TEXT> | CrossRef | BookVar )*
Part of General rule
Insert variable
Like all other elements
Only where allowed
Choose attribute value
from drop-down list
Update book !

57. 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

58. ABCM
Attribute-based
Define attributes in EDD
Any applicable element
Includes children
Condition schemes
Define schemes once
Color, filter, validate

59. Attribute-based conditions
Defined in EDD Element (Container): Section
General rule: Title, Body?, Section*
Attributes applied to Attribute list
1. Name: id Unique ID Optional
all useful elements 2. Name: conref String Optional
3. Name: Version Choice Optional
Define attributes once Choices: VersionA, VersionB, VersionC
4. Name: Product Strings Optional
Copy-paste attributes to Element (Container): Para
all applicable elements General rule: (<TEXT> | CrossRef | BookVar )*
Attribute list
1. Name: Version Choice Optional
Conditions applicable Choices: VersionA, VersionB, VersionC
only to elements 2. Name: Product Strings Optional

60. ABCM schemes
Library of
schemes
Coloring schemes
Filtering schemes
Validation schemes
Attribute-based
Match values
Combined matches
Execute rule

61. 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

62. 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

63. Filtering books
Master
Product A
Product A
DEU
Product B Product B
NLD

64. Modular EDD - step 7
Element (Container): Para
General rule: (<TEXT> | CrossRef | BookVar )*
Attribute list
1. Name: Version Choice Optional
Choices: VersionA, VersionB, VersionC
2. Name: Product Strings Optional
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]>

65. Step 8: Creating books
from reuse modules

66. Limiting chaos
Library of subtopics
Standard warnings
Standard steps
Consistent topics
Follow machine design
Follow main tasks
Create topic templates
Consistent metadata

67. Consistent topics
Machine modules
Functional description
Operating
Maintaining, cleaning
Testing, adjusting
Troubleshooting
Removing, Mounting
Replacing parts

68. Consistent topics
Describe all buttons
Follow GUI design
One topic per screen
Describe procedures
Start-of-day
Normal operation
Maintenance
End-of-day

69. Possible subtopics
Notes, warnings
Procedure steps
Images + poslists
Button descriptions
Parameter
descriptions
Examples
Specifications

70. Trade-off
Subtopics
Create more modules
Keeping track of usage
Complex dependencies
Conditional text
Create complex
modules
Change one, change all
Copies after filtering

71. 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

72. Keeping track
Excel workbook
Available topics
Versions, revisions
Status and planning
Available translations
Usage information
Manually in Excel
Via InsetPlus reports

73. Step 9: Publishing
to various layouts

74. Formatting outside EDD
Change formatting Style
without editing EDD EDD Tags
guide
Paragraph format tags
Structure Formatting
Separate style guide
Advantages: Document
Title
Accessible formatting
FirstPar
Easier bookmarking BulletList
Multiple style guides ListItem

75. Import style guide formats
Page layouts
Page setup, sizes
Fixed elements, flows
Reference pages
Repository for icons
Paragraph formats
Character formats

76. 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

77. Multiple style guides

78. Modular documentation
Writing topics
Assembling books
Updating Xrefs
Filtering books
Applying layouts
Publishing books

79. Questions ?

80. More info & materials:
send e-mail to
jang@jang.nl