0
Modular documentationin Structured FrameMakerJang F.M. GraatJANG Communication
Who’s talking ?Jang F.M. GraatPhysics, Psychology,Philosophy20+ years TechWriter, Trainer, Consultant15+ years companyJANG...
Agenda for this tutorial Step 1: Defining your modular structure Step 2: Defining the top-level elements Step 3: Defining ...
Agenda for this tutorial Step 6: Handling cross-references in reuse modules Step 7: Allowing variability in reuse modules ...
Step 1: Defining your modular structure
Modular design: top-down                    Book TOC      Chapter          Chapter   IndexSection   Section          Secti...
Modular design: bottom-up                    Book TOC      Chapter          Chapter   IndexSection   Section          Sect...
Modules: reusability   Modules    Maps     Pubs
Granularity of modulesNumber of modulesGeneric vs. specificImpact on reusabilityHow much chaoscan you manage ?Multiple lay...
Topic-based writingAnswer one question  “What is this for ?”  “How does it work ?”  “How do I do this ?”  “What are my opt...
Writing for reusability Generic topics Less is more Clear structure Rigid structure Generic vs. specific   Separate variab...
Nesting of modulesAllow modules tocontain other modulesModule used atvarious levels inpublicationsFormatting issues  Level...
Naming conventionsStrict naming rules  Recognizable  Unique namesPrefixed types  task-RemoveBoard  ref-FileSaveOptions  co...
Finding modulesMeaningful titles  Valid for which part ?  Include version info ?Attributes of mainmodule elementsDirectory...
Document Type DefinitionDefines valid structure  Book                            <!DOCTYPE MyBook [     Chapter           ...
EDD: Element DefinitionDocElement definitions  Unique name  General rule: structure  Attributes  Formatting rulesDTD + for...
Modular EDD - step 1                                 EDD Version is 8.0 Book                                 Element (Cont...
Step 2: Defining thehighest-level elements
Documentation systems        Book      Book Fm       Chapter   Ditamap        Flow      File       Content   Content   Dita
Highest-level elements                       Element (Container): BookAvailable as root in     General rule: Chapter+     ...
Why is this important ? Modular documents               File: chapterA   Each file = one topic     Chapter                ...
Granularity of modulesNumber of modulesGeneric vs. specificImpact on reusabilityHow much chaoscan you manage ?Multiple lay...
Modular EDD - step 2                                 EDD Version is 8.0 Book                            Element (Container...
Step 3: Defining the layout properties
Defining layout properties Layout is for users Company style guide Rigid system   No exceptions !!!   No “tweaking” !!! Ne...
Direct formatting in EDDAll formatting options                          Element (Container): Body                         ...
Using format control lists Advantages  Usually gathered in one  section of the EDD  Reuse of the same fcl  for multiple el...
Formatting outside EDDChange formatting                                     Stylewithout editing EDD        EDD           ...
Paragraph format tagsUnique format tags                Style                            EDD  Choose intelligent           ...
Using context rulesAll Contexts rule             Element (Container): Body                                General rule: <T...
Modular EDD - step 3Title element  Section title depends  on level of nesting  Level rule in EDDParagraph format tags  Req...
Step 4: Using text insets   to reuse modules
FrameMaker text insetsImport entire flowDisadvantages  Inset source required  No search mechanism  No previewing  No check...
West Street ConsultingFrameMaker ACE Russ Ward  Full-time tech writer + part-time software developer  Website: www.weststr...
InsetPlusElement-level linkingAdvantages  Any element in file  User-friendly interface  Search & preview  Check on validit...
InsetPlus linking methodElement attributes  Source: Unique ID  Target: conrefInserting & updating  Insert empty element  L...
InsetPlus: further options Tracking information   Where is source used ?   Updating all references Linking options   Editi...
Modular EDD - step 4     Element (Container): Book       General rule:    Chapter+       Valid as the highest-level elemen...
Step 5: Creating your own CMS
Content ManagementKeep track of stuff  Storing modules  Searching modules  Validity for publications  Review & translation...
Content ManagementFinding content  Clear structure  Strict namingWithout a CMS ?  Store in repositories  Restrict modulari...
Repository files Reusable elements  Wrapper with info  Enable search & checks  Printable as catalog Bundle reuse modules  ...
Organize repository files Collect in book   Printing full catalog   Easier updating   Easier to manage Division of modules...
Modular EDD - step 5Same EDD in all files         Element (Container): ReuseModule                                General ...
Step 6: Handling Xrefs  in reuse modules
Xrefs in FrameMakerAllowing Xrefs  Marker attribute in all  referrable elements  CrossReference  element with target  attr...
Xrefs in FrameMakerXrefs to other files  Source file required  Source file changed !Prepare for Xrefs  Manually define mar...
Xrefs in FrameMakerUpdating Xrefs                                    Book  Source files requiredXref to inset text  Xref t...
XRef WizardAttribute-based linking  Unique IDs targeted  No file names usedAdvantages  No file-dependence  Works with text...
XRef WizardUpdating Xrefs                                       Book  Book-level process  Only files in bookXref to inset ...
XRef WizardBook level  Resolves all Xrefs  Reports conflicts  Multiple targets    Choice of candidates    Allows jumping i...
Modular EDD - step 6     Element (Container): Para       General rule:   (<TEXT> | CrossRef )*     Element (CrossReference...
Step 7: Allowing variability    in reuse modules
Variable info: FM variables Special -> Variables   Defined per file   Import to each file   after changing value Use in te...
Variables in the EDDDefine element             Element (Container): BookVar                             General rule:     ...
Variables in the EDDAllow element               Element (Container): Para                              General rule:   ( <...
Conditional text: FMmethod Condition tags   Defined per document   Applied per text section   Works with text insets Hide ...
ABCMAttribute-based  Define attributes in EDD  Any applicable element  Includes childrenCondition schemes  Define schemes ...
Attribute-based conditions Defined in EDD              Element (Container): Section                               General ...
ABCM schemesLibrary ofschemes  Coloring schemes  Filtering schemes  Validation schemesAttribute-based  Match values  Combi...
Coloring source files Coloring scheme  Define color options  Define matching rules  Store coloring scheme Applying a schem...
Filtering source files Filtering scheme   Define matching rules   Store filtering scheme Applying a scheme   ABCM > Filter...
Filtering books                          Master                  Product A                                    Product A   ...
Modular EDD - step 7     Element (Container): Para         General rule: (<TEXT> | CrossRef | BookVar )*         Attribute...
Step 8: Creating books from reuse modules
Limiting chaosLibrary of subtopics  Standard warnings  Standard stepsConsistent topics  Follow machine design  Follow main...
Consistent topicsMachine modules  Functional description  Operating  Maintaining, cleaning  Testing, adjusting  Troublesho...
Consistent topicsDescribe all buttons  Follow GUI design  One topic per screenDescribe procedures  Start-of-day  Normal op...
Possible subtopicsNotes, warningsProcedure stepsImages + poslistsButton descriptionsParameterdescriptionsExamplesSpecifica...
Trade-offSubtopics  Create more modules  Keeping track of usage  Complex dependenciesConditional text  Create complex  mod...
Publishing booksOrder of final steps  Update all insets  Resolve all XRefs  Update book  Save book as PDFOne book per prod...
Keeping trackExcel workbook  Available topics  Versions, revisions  Status and planning  Available translationsUsage infor...
Step 9: Publishingto various layouts
Formatting outside EDDChange formatting                                     Stylewithout editing EDD        EDD           ...
Import style guide formats Page layouts   Page setup, sizes   Fixed elements, flows Reference pages   Repository for icons...
Using various templatesSame style tags  Copy template  Change page layout  Change para formats  Change char formatsInclude...
Multiple style guides
Modular documentationWriting topicsAssembling booksUpdating XrefsFiltering booksApplying layoutsPublishing books
Questions ?
More info & materials:   send e-mail to   jang@jang.nl
Upcoming SlideShare
Loading in...5
×

Modular documentation in Structured FrameMaker

824

Published on

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.

Published in: Education
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
824
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
31
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

Transcript of "Modular documentation in Structured FrameMaker"

  1. 1. Modular documentationin Structured FrameMakerJang F.M. GraatJANG Communication
  2. 2. Who’s talking ?Jang F.M. GraatPhysics, Psychology,Philosophy20+ years TechWriter, Trainer, Consultant15+ years companyJANG CommunicationSelf-taught FM expert
  3. 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. 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. 5. Step 1: Defining your modular structure
  6. 6. Modular design: top-down Book TOC Chapter Chapter IndexSection Section Section Topic Topic Topic
  7. 7. Modular design: bottom-up Book TOC Chapter Chapter IndexSection Section Section Topic Topic Topic
  8. 8. Modules: reusability Modules Maps Pubs
  9. 9. Granularity of modulesNumber of modulesGeneric vs. specificImpact on reusabilityHow much chaoscan you manage ?Multiple layers of(nested) modules
  10. 10. Topic-based writingAnswer 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. 11. Writing for reusability Generic topics Less is more Clear structure Rigid structure Generic vs. specific Separate variability Use conditional text ?
  12. 12. Nesting of modulesAllow modules tocontain other modulesModule used atvarious levels inpublicationsFormatting issues Levels of titles Font families, sizes Indentation, tabs
  13. 13. Naming conventionsStrict naming rules Recognizable Unique namesPrefixed types task-RemoveBoard ref-FileSaveOptions concept-Mod5402 t-5402-Adjust
  14. 14. Finding modulesMeaningful titles Valid for which part ? Include version info ?Attributes of mainmodule elementsDirectory structureExcel sheet to keeptrack of everything
  15. 15. Document Type DefinitionDefines 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. 16. EDD: Element DefinitionDocElement definitions Unique name General rule: structure Attributes Formatting rulesDTD + formattingPart of every FM file Imported from EDD file
  17. 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. 18. Step 2: Defining thehighest-level elements
  19. 19. Documentation systems Book Book Fm Chapter Ditamap Flow File Content Content Dita
  20. 20. Highest-level elements Element (Container): BookAvailable 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. 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. 22. Granularity of modulesNumber of modulesGeneric vs. specificImpact on reusabilityHow much chaoscan you manage ?Multiple layers of(nested) modules
  23. 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. 24. Step 3: Defining the layout properties
  25. 25. Defining layout properties Layout is for users Company style guide Rigid system No exceptions !!! No “tweaking” !!! Nesting of modules Various publications
  26. 26. Direct formatting in EDDAll 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 StopsEverything available in Tab stop position: 11.0mm Tab stop position: 18.0mmparagraph designer Tab stop position: 21.0mm
  27. 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. 28. Formatting outside EDDChange formatting Stylewithout editing EDD EDD Tags guideParagraph format tags Structure FormattingSeparate style guideAdvantages: Document Title Accessible formatting FirstPar Easier bookmarking BulletList Multiple style guides ListItem
  29. 29. Paragraph format tagsUnique format tags Style EDD Choose intelligent guide namesImporting EDD Create formats on input Paragraph tags addedFormatting in template Paragraph designer Always use “Update all”
  30. 30. Using context rulesAll Contexts rule Element (Container): Body General rule: <TEXT> Text format rulesContext 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. 31. Modular EDD - step 3Title element Section title depends on level of nesting Level rule in EDDParagraph format tags Required heading level Note: no exceptions ! Nested context rule
  32. 32. Step 4: Using text insets to reuse modules
  33. 33. FrameMaker text insetsImport entire flowDisadvantages Inset source required No search mechanism No previewing No check on structure
  34. 34. West Street ConsultingFrameMaker ACE Russ Ward Full-time tech writer + part-time software developer Website: www.weststreetconsulting.comExtremely useful plug-ins for FrameMaker Xref Wizard ( $ 35 per seat ) FrameSLT ( $ 100 per seat ) InsetPlus ( free ) ABCM ( free )
  35. 35. InsetPlusElement-level linkingAdvantages Any element in file User-friendly interface Search & preview Check on validity Updating quick & easy Tracking of usage
  36. 36. InsetPlus linking methodElement attributes Source: Unique ID Target: conrefInserting & updating Insert empty element Link to source element Update indivual inset Update all insets in file
  37. 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. 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. 39. Step 5: Creating your own CMS
  40. 40. Content ManagementKeep track of stuff Storing modules Searching modules Validity for publications Review & translationDatabase needed ? No magic involved Manage the chaos
  41. 41. Content ManagementFinding content Clear structure Strict namingWithout a CMS ? Store in repositories Restrict modularity Use nested modules Document validity info
  42. 42. Repository files Reusable elements Wrapper with info Enable search & checks Printable as catalog Bundle reuse modules Machine section Software section Clear subdivision
  43. 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. 44. Modular EDD - step 5Same 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 rulesSpecial 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. 45. Step 6: Handling Xrefs in reuse modules
  46. 46. Xrefs in FrameMakerAllowing Xrefs Marker attribute in all referrable elements CrossReference element with target attribute Both attributes optionalCreating Xrefs Enter CrossRef element Link to available marker
  47. 47. Xrefs in FrameMakerXrefs to other files Source file required Source file changed !Prepare for Xrefs Manually define marker FM attribute editor Use unique names
  48. 48. Xrefs in FrameMakerUpdating Xrefs Book Source files requiredXref 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. 49. XRef WizardAttribute-based linking Unique IDs targeted No file names usedAdvantages No file-dependence Works with text insets Updating quick & easy Reports with links
  50. 50. XRef WizardUpdating Xrefs Book Book-level process Only files in bookXref to inset text See X. X Xref defined in attribute independent of filename Marker recognized Automatic relinking See X. X
  51. 51. XRef WizardBook level Resolves all Xrefs Reports conflicts Multiple targets Choice of candidates Allows jumping into Fast and easy Update book after this
  52. 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. 53. Step 7: Allowing variability in reuse modules
  54. 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. 55. Variables in the EDDDefine 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. 56. Variables in the EDDAllow element Element (Container): Para General rule: ( <TEXT> | CrossRef | BookVar )* Part of General ruleInsert variable Like all other elements Only where allowed Choose attribute value from drop-down list Update book !
  57. 57. Conditional text: FMmethod 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. 58. ABCMAttribute-based Define attributes in EDD Any applicable element Includes childrenCondition schemes Define schemes once Color, filter, validate
  59. 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. 60. ABCM schemesLibrary ofschemes Coloring schemes Filtering schemes Validation schemesAttribute-based Match values Combined matches Execute rule
  61. 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. 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. 63. Filtering books Master Product A Product A DEU Product B Product B NLD
  64. 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. 65. Step 8: Creating books from reuse modules
  66. 66. Limiting chaosLibrary of subtopics Standard warnings Standard stepsConsistent topics Follow machine design Follow main tasks Create topic templatesConsistent metadata
  67. 67. Consistent topicsMachine modules Functional description Operating Maintaining, cleaning Testing, adjusting Troubleshooting Removing, Mounting Replacing parts
  68. 68. Consistent topicsDescribe all buttons Follow GUI design One topic per screenDescribe procedures Start-of-day Normal operation Maintenance End-of-day
  69. 69. Possible subtopicsNotes, warningsProcedure stepsImages + poslistsButton descriptionsParameterdescriptionsExamplesSpecifications
  70. 70. Trade-offSubtopics Create more modules Keeping track of usage Complex dependenciesConditional text Create complex modules Change one, change all Copies after filtering
  71. 71. Publishing booksOrder of final steps Update all insets Resolve all XRefs Update book Save book as PDFOne book per product Back-up published book Include all chapters
  72. 72. Keeping trackExcel workbook Available topics Versions, revisions Status and planning Available translationsUsage information Manually in Excel Via InsetPlus reports
  73. 73. Step 9: Publishingto various layouts
  74. 74. Formatting outside EDDChange formatting Stylewithout editing EDD EDD Tags guideParagraph format tags Structure FormattingSeparate style guideAdvantages: Document Title Accessible formatting FirstPar Easier bookmarking BulletList Multiple style guides ListItem
  75. 75. Import style guide formats Page layouts Page setup, sizes Fixed elements, flows Reference pages Repository for icons Paragraph formats Character formats
  76. 76. Using various templatesSame style tags Copy template Change page layout Change para formats Change char formatsInclude all tagsAdd fixed elements Standard master pages
  77. 77. Multiple style guides
  78. 78. Modular documentationWriting topicsAssembling booksUpdating XrefsFiltering booksApplying layoutsPublishing books
  79. 79. Questions ?
  80. 80. More info & materials: send e-mail to jang@jang.nl
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×