• Like

Modular documentation in Structured FrameMaker

  • 557 views
Uploaded 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 …

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.

More in: Education
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
557
On Slideshare
0
From Embeds
0
Number of Embeds
1

Actions

Shares
Downloads
22
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. Modular documentationin Structured FrameMakerJang F.M. GraatJANG Communication
  • 2. Who’s talking ?Jang F.M. GraatPhysics, Psychology,Philosophy20+ years TechWriter, Trainer, Consultant15+ years companyJANG CommunicationSelf-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 IndexSection Section Section Topic Topic Topic
  • 7. Modular design: bottom-up Book TOC Chapter Chapter IndexSection Section Section Topic Topic Topic
  • 8. Modules: reusability Modules Maps Pubs
  • 9. Granularity of modulesNumber of modulesGeneric vs. specificImpact on reusabilityHow much chaoscan you manage ?Multiple layers of(nested) modules
  • 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. Writing for reusability Generic topics Less is more Clear structure Rigid structure Generic vs. specific Separate variability Use conditional text ?
  • 12. Nesting of modulesAllow modules tocontain other modulesModule used atvarious levels inpublicationsFormatting issues Levels of titles Font families, sizes Indentation, tabs
  • 13. Naming conventionsStrict naming rules Recognizable Unique namesPrefixed types task-RemoveBoard ref-FileSaveOptions concept-Mod5402 t-5402-Adjust
  • 14. Finding modulesMeaningful titles Valid for which part ? Include version info ?Attributes of mainmodule elementsDirectory structureExcel sheet to keeptrack of everything
  • 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. EDD: Element DefinitionDocElement definitions Unique name General rule: structure Attributes Formatting rulesDTD + formattingPart 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 thehighest-level elements
  • 19. Documentation systems Book Book Fm Chapter Ditamap Flow File Content Content Dita
  • 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. 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 modulesNumber of modulesGeneric vs. specificImpact on reusabilityHow much chaoscan 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 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. 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 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. 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. 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. 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. Step 4: Using text insets to reuse modules
  • 33. FrameMaker text insetsImport entire flowDisadvantages Inset source required No search mechanism No previewing No check on structure
  • 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. InsetPlusElement-level linkingAdvantages Any element in file User-friendly interface Search & preview Check on validity Updating quick & easy Tracking of usage
  • 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. 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 ManagementKeep track of stuff Storing modules Searching modules Validity for publications Review & translationDatabase needed ? No magic involved Manage the chaos
  • 41. Content ManagementFinding content Clear structure Strict namingWithout 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 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. Step 6: Handling Xrefs in reuse modules
  • 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. 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. 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. 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. 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. XRef WizardBook 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 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. 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. 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. ABCMAttribute-based Define attributes in EDD Any applicable element Includes childrenCondition 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 schemesLibrary ofschemes Coloring schemes Filtering schemes Validation schemesAttribute-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 chaosLibrary of subtopics Standard warnings Standard stepsConsistent topics Follow machine design Follow main tasks Create topic templatesConsistent metadata
  • 67. Consistent topicsMachine modules Functional description Operating Maintaining, cleaning Testing, adjusting Troubleshooting Removing, Mounting Replacing parts
  • 68. Consistent topicsDescribe all buttons Follow GUI design One topic per screenDescribe procedures Start-of-day Normal operation Maintenance End-of-day
  • 69. Possible subtopicsNotes, warningsProcedure stepsImages + poslistsButton descriptionsParameterdescriptionsExamplesSpecifications
  • 70. Trade-offSubtopics Create more modules Keeping track of usage Complex dependenciesConditional text Create complex modules Change one, change all Copies after filtering
  • 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. Keeping trackExcel workbook Available topics Versions, revisions Status and planning Available translationsUsage information Manually in Excel Via InsetPlus reports
  • 73. Step 9: Publishingto various layouts
  • 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. Import style guide formats Page layouts Page setup, sizes Fixed elements, flows Reference pages Repository for icons Paragraph formats Character formats
  • 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. Multiple style guides
  • 78. Modular documentationWriting topicsAssembling booksUpdating XrefsFiltering booksApplying layoutsPublishing books
  • 79. Questions ?
  • 80. More info & materials: send e-mail to jang@jang.nl