Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Create your own $35 CMS
in Structured FrameMaker
Jang F.M. Graat
JANG Communication
Presented at tcword 2010 - © JANG Comm...
Who’s talking ?
Jang F.M. Graat
Studied Physics,
Psychology, Philosophy
20+ years Tech Writer,
Trainer, Consultant
15+ yea...
Agenda
Step 1: Create reusable modules
Step 2: Create your CMS
Step 3: Enable cross-references
Step 4: Create books from y...
Step 1:
Create reusable modules
Presented at tcword 2010 - © JANG Communication 2010
Modular documentation
Presented at tcword 2010 - © JANG Communication 2010
FrameMaker text insets
Import entire flows
Disadvantages
Inset source required
No search mechanism
No previewing
No check o...
West Street Consulting
FrameMaker ACE Russ Ward
Full-time tech writer + part-time software developer
Website: www.weststre...
InsetPlus
Element-level linking
Advantages
Any element in file
User-friendly interface
Search & preview
Check on validity
U...
InsetPlus linking method
Element attributes
Source: Unique ID
Target: conref
Inserting & updating
Insert empty element
Lin...
InsetPlus: further options
Tracking information
Where is source used ?
Updating all references
Linking options
Editing con...
Define your EDD
Reusable elements
id and conref attributes
Metadata attributes
Any element ?
Granularity
Manage the chaos
U...
Step 2:
Create your CMS
Presented at tcword 2010 - © JANG Communication 2010
Content Management
Keep track of stuff
Storing modules
Searching modules
Validity for publications
Review & translation
Da...
Content Management
Finding content
Clear structure
Strict naming
Without a CMS ?
Store in repositories
Restrict modularity...
Repository files
Reusable elements
Metadata in attributes
Enable search & checks
Printable as catalog
Bundle reuse modules
...
Catalog of available modules
Special formatting
If included in Repository
Show element id
Include metadata
Print full cata...
Special formatting in EDD
Element (Container): concept
General rule: title, shortdesc?, context?, conbody, links?
Attribut...
Organize repository files
Division of modules
One file per assembly ?
One file per topic type ?
One file per product ?
Collect...
Organize image files
Divide into categories
Types of image files
Machine-specific images
Language variants
One dir per langua...
Organize publications
Always use books
Required for CMS
Easier to manage
Language variants
Same language codes
Versions
Fu...
Step 3:
Enable cross-references
Presented at tcword 2010 - © JANG Communication 2010
Xrefs in FrameMaker
Enabling Xrefs
Marker attribute in all
referrable elements
CrossReference element
with target attribut...
Xrefs in FrameMaker
Element (Container): Para
General rule: (<TEXT> | CrossRef )*
Element (CrossReference): CrossRef
Attri...
Xrefs in FrameMaker
Xrefs to other files
Ref’d file required
Changes in ref’d file !
Prepare for Xrefs
Manually define marker
...
Xrefs in FrameMaker
Updating Xrefs
Source files required
Xref to inset text
Xref to inset source,
not to inset reference
Ma...
XRef Wizard
Attribute-based linking
Unique IDs targeted
No file names used
Advantages
No file-dependence
Works with text ins...
XRef Wizard
Updating Xrefs
Book-level process
Only files in book
Xref to inset text
Xref defined in attribute
independent of...
XRef Wizard
Book level
Resolves all Xrefs
Reports conflicts
Multiple targets
Choice of candidates
Allows jumping into
Fast ...
Step 4:
Create books
Presented at tcword 2010 - © JANG Communication 2010
Preparing a publication
Create new Book
Create empty Chapters
Add to the book
Import EDD to all
Import formats to all
Set ...
Add reuse elements
Insert empty element
Use InsetPlus
“Edit Inset Element”
Select repository file
Valid elements are listed...
Publishing books
Order of final steps
Select book file
Open all chapters
Update all insets
Resolve all XRefs
Update book
Sav...
Keeping track
Excel workbook
Available topics
Versions, revisions
Status and planning
Available translations
Usage informa...
Translation management
Directory structure
Language codes
Translate repositories
Translate images
Copy of book
Script to p...
Questions ?
Presented at tcword 2010 - © JANG Communication 2010
More info:
send e-mail to
jang@jang.nl
Presented at tcword 2010 - © JANG Communication 2010
Upcoming SlideShare
Loading in …5
×

Create your own $35 CMS in Structured FrameMaker

897 views

Published on

Content Management Systems for technical documentation can be expensive and do not provide a magical solution to all your reuse problems. Often, going through the excercise of building your own custom CMS helps you define your set of requirements, so you will be much better prepared to purchase the exact right CMS for you a couple of years down the road. Building your own CMS based on structured FrameMaker is not a very difficult task and teaches you a lot about all the possible issues when starting with modular documentation and reuse.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Create your own $35 CMS in Structured FrameMaker

  1. 1. Create your own $35 CMS in Structured FrameMaker Jang F.M. Graat JANG Communication Presented at tcword 2010 - © JANG Communication 2010
  2. 2. Who’s talking ? Jang F.M. Graat Studied Physics, Psychology, Philosophy 20+ years Tech Writer, Trainer, Consultant 15+ years company JANG Communication Self-taught FM expert Presented at tcword 2010 - © JANG Communication 2010
  3. 3. Agenda Step 1: Create reusable modules Step 2: Create your CMS Step 3: Enable cross-references Step 4: Create books from your CMS Presented at tcword 2010 - © JANG Communication 2010
  4. 4. Step 1: Create reusable modules Presented at tcword 2010 - © JANG Communication 2010
  5. 5. Modular documentation Presented at tcword 2010 - © JANG Communication 2010
  6. 6. FrameMaker text insets Import entire flows Disadvantages Inset source required No search mechanism No previewing No check on structure Presented at tcword 2010 - © JANG Communication 2010
  7. 7. West Street Consulting FrameMaker ACE Russ Ward Full-time tech writer + part-time software developer Website: www.weststreetconsulting.com Extremely useful plug-ins for FM7, FM8, FM9 Xref Wizard ( $ 35 per seat ) FrameSLT ( $ 100 per seat ) InsetPlus ( free ) AXCM ( free ) Presented at tcword 2010 - © JANG Communication 2010
  8. 8. InsetPlus Element-level linking Advantages Any element in file User-friendly interface Search & preview Check on validity Updating quick & easy Tracking of usage Presented at tcword 2010 - © JANG Communication 2010
  9. 9. 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 Presented at tcword 2010 - © JANG Communication 2010
  10. 10. 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 Presented at tcword 2010 - © JANG Communication 2010
  11. 11. Define your EDD Reusable elements id and conref attributes Metadata attributes Any element ? Granularity Manage the chaos Use nested elements 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 3. Name: version String Required 4. Name: validity String Optional 5. Name: author String Required 6. Name: date String Required Presented at tcword 2010 - © JANG Communication 2010
  12. 12. Step 2: Create your CMS Presented at tcword 2010 - © JANG Communication 2010
  13. 13. Content Management Keep track of stuff Storing modules Searching modules Validity for publications Review & translation Database needed ? No magic involved Manage the chaos Presented at tcword 2010 - © JANG Communication 2010
  14. 14. Content Management Finding content Clear structure Strict naming Without a CMS ? Store in repositories Restrict modularity Practice discipline !!! Presented at tcword 2010 - © JANG Communication 2010
  15. 15. Repository files Reusable elements Metadata in attributes Enable search & checks Printable as catalog Bundle reuse modules Per machine section Per software section Clear subdivisions Presented at tcword 2010 - © JANG Communication 2010
  16. 16. Catalog of available modules Special formatting If included in Repository Show element id Include metadata Print full catalog Searchable PDF Helps author reuse Presented at tcword 2010 - © JANG Communication 2010
  17. 17. Special formatting in EDD Element (Container): concept General rule: title, shortdesc?, context?, conbody, links? Attribute list 1. Name: id UniqueID Optional 2. Name: conref String Optional 3. Name: version String Optional 4. Name: validity String Optional Prefix rules 1. If context is: [ id != “” ] Prefix: concept:tidnversion:t<$attribute[version]>nvalid for:t<$attribute[validity]> Text format rules 1. If context is: [ id != “” ] Use paragraph format: RepHeading Presented at tcword 2010 - © JANG Communication 2010
  18. 18. Organize repository files Division of modules One file per assembly ? One file per topic type ? One file per product ? Collect in books Easier to manage Language variants Keep same structure Presented at tcword 2010 - © JANG Communication 2010
  19. 19. Organize image files Divide into categories Types of image files Machine-specific images Language variants One dir per language One dir for generic pics Keep same structure Presented at tcword 2010 - © JANG Communication 2010
  20. 20. Organize publications Always use books Required for CMS Easier to manage Language variants Same language codes Versions Full books in subdirs Include all chapters Presented at tcword 2010 - © JANG Communication 2010
  21. 21. Step 3: Enable cross-references Presented at tcword 2010 - © JANG Communication 2010
  22. 22. Xrefs in FrameMaker Enabling Xrefs Marker attribute in all referrable elements CrossReference element with target attribute Both attributes optional Creating Xrefs Enter CrossRef element Link to available marker Presented at tcword 2010 - © JANG Communication 2010
  23. 23. Xrefs in FrameMaker 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 Presented at tcword 2010 - © JANG Communication 2010
  24. 24. Xrefs in FrameMaker Xrefs to other files Ref’d file required Changes in ref’d file ! Prepare for Xrefs Manually define marker FM attribute editor Use unique names Presented at tcword 2010 - © JANG Communication 2010
  25. 25. 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 relinking See X. X See X. X Book Presented at tcword 2010 - © JANG Communication 2010
  26. 26. 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 Presented at tcword 2010 - © JANG Communication 2010
  27. 27. XRef Wizard Updating Xrefs Book-level process Only files in book Xref to inset text Xref defined in attribute independent of filename Marker recognized Automatic relinking See X. X See X. X Book Presented at tcword 2010 - © JANG Communication 2010
  28. 28. XRef Wizard Book level Resolves all Xrefs Reports conflicts Multiple targets Choice of candidates Allows jumping into Fast and easy Update book after this Presented at tcword 2010 - © JANG Communication 2010
  29. 29. Step 4: Create books Presented at tcword 2010 - © JANG Communication 2010
  30. 30. Preparing a publication Create new Book Create empty Chapters Add to the book Import EDD to all Import formats to all Set required info Book attributes Presented at tcword 2010 - © JANG Communication 2010
  31. 31. Add reuse elements Insert empty element Use InsetPlus “Edit Inset Element” Select repository file Valid elements are listed Select required element Click OK twice Continue until done Presented at tcword 2010 - © JANG Communication 2010
  32. 32. Publishing books Order of final steps Select book file Open all chapters Update all insets Resolve all XRefs Update book Save book as PDF Presented at tcword 2010 - © JANG Communication 2010
  33. 33. Keeping track Excel workbook Available topics Versions, revisions Status and planning Available translations Usage information Manually in Excel Via InsetPlus reports Presented at tcword 2010 - © JANG Communication 2010
  34. 34. Translation management Directory structure Language codes Translate repositories Translate images Copy of book Script to process language codes Presented at tcword 2010 - © JANG Communication 2010
  35. 35. Questions ? Presented at tcword 2010 - © JANG Communication 2010
  36. 36. More info: send e-mail to jang@jang.nl Presented at tcword 2010 - © JANG Communication 2010

×