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 jang@jang.nl