Your SlideShare is downloading. ×
Implementing Structured FrameMaker
Upcoming SlideShare
Loading in...5

Thanks for flagging this SlideShare!

Oops! An error has occurred.

Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Implementing Structured FrameMaker


Published on

I gave this presentation at the 2007 STC Conference in Minneapolis, MN

I gave this presentation at the 2007 STC Conference in Minneapolis, MN

1 Like
  • Be the first to comment

No Downloads
Total Views
On Slideshare
From Embeds
Number of Embeds
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

No notes for slide
  • Transcript

    • 1. Implementing Structured Documentation May 5, 2007 Denise Kadilak – Technical Writer
    • 2. Agenda
      • Overview
      • Why Change?
      • Why Structure?
      • Training
      • Getting Started
      • Generating Output
    • 3. Overview
      • Blackbaud’s implementation plan
        • First year
          • Selected a core group of team members
            • Trained
            • Evaluated existing documentation
            • Created, tested, and edited the necessary supporting files (EDD, DTD, structure application)
          • Applied the new structure to a couple small pilot projects
        • Second year
          • Introduced more writers to structured authoring
          • Started work on a large enterprise project using structure-based documentation
          • Released this March our first large structure-based project
        • Future plans
          • Introduce other product documentation to structured authoring
          • Convert remaining small projects
    • 4. Why Change?
      • Projects too large and complex for standard FrameMaker
        • Exceeded conditional text limitation
        • Increased demand for customized documentation sets
      • Separate documentation sets not an attractive option
        • Inefficient
        • Inaccurate
    • 5. Why Structure?
      • Growth potential
        • Grows with our documents
      • Semantic markup information
        • Necessary for Web 2.0
          • Allows computers to better process information
          • Locates specific information faster and more accurately
      • Elements and metadata
        • Houses all information in one source document
    • 6. Why Structure?
      • Content reuse/Reduce duplication
        • Reuse limitation
          • Not using topic-based authoring
        • InsetPlus accommodates limited reuse
          • InsetPlus is a shareware application that works much better than FrameMaker’s text inset utility
          • The structured view makes it easy to see exactly what text belongs to what inset
        • Structure results in improved consistency
          • EDD restrictions; writers must follow the rules
          • Documentation structure created
    • 7. Why Structure?
      • Exchange content between incompatible applications
        • XML is platform and vendor neutral
      • Satisfy industry/organizational trends
        • Customized help is on the increase
          • Our products can stand alone or integrate, so user instructions vary based on what the client owns
          • Using attributes we can generate one set of documentation for a single-product users, another for a two-product user, and another for a user who owns all products. We can also customize docs for larger clients.
        • Topic-based authoring is an option
    • 8. Training
      • Implementing a structured workflow is not easy
        • Professional training is a must
          • We trained with Scriptorium Publishing
      • Participating writers must be dedicated to the process
        • Even with training this is a difficult process
        • If everyone involved is not 100% dedicated to learning and implementing structured authoring, you are wasting your money
          • Requires extra time
          • Requires extra research
          • Requires extra frustration
    • 9. Training
      • Professional training is expensive
        • Select an authoring group with a designated project lead
          • Our group consisted of five writers selected from the 14-member documentation team
        • Provide background information explaining structured authoring
          • Web sites
          • White papers
          • Journal articles
        • Train before training
          • All five writers had to become proficient with the Introduction to Structured FrameMaker workbook
          • Because of this preparation, we were able to begin our training at the intermediate level
    • 10. Getting Started
      • Analyze current content
        • Identify content elements
          • If you generate book output, identify top-level elements such as Chapter, Appendix, Glossary
        • Identify content reuse areas
    • 11. Getting Started
      • Consider legacy documents
        • Conversion tables in FrameMaker can automate a good deal of the task
          • Conversion tables map unstructured FrameMaker paragraph and character formats to elements
          • Creating tables is not easy and requires a solid understanding of structured FrameMaker and your existing documents
          • Best conversion candidates include documents created using a style-based authoring tool, such as FrameMaker, in which the styles were used consistently
    • 12. Getting Started
      • Determine your documentation design
        • Important if you have more than one writer working on a project
        • Ensures consistency
          • How to begin a procedure
          • How to end a procedure
          • Graphic placement
          • Field definitions
      • Determine how to generate your output
        • Structured application
        • Third-party software
    • 13. Getting Started: Structured App vs. WWePP
    • 14. Getting Started
      • Create the necessary files
        • EDD
          • The EDD (element definition document) is the structured file template. It defines the element catalogue and the element relationships. You can also include formatting information.
          • Investigate existing options. For example, rather than start from scratch, you may want to use DocBook or DITA.
          • Test your EDD
          • Use only one EDD
        • Formatting template
          • You can set up formatting in the EDD or in a separate formatting document
    • 15. Getting Started: Structured Application
        • DTD (Document Type Definition)
          • Required if you use the structured application for output
          • Defines the element names and valid content and attributes for each element
          • In FrameMaker, you can create a DTD using your EDD or vice versa, but the DTD file does not contain formatting information
        • Read/Write Rules
          • Required if you use the structured application for output
          • Contains mapping rules, controlling how XML is exported from your structured documents
        • Structured Application Definition Document
          • Required if you use the structured application for output
          • Stores application settings, such as the application name and the location of the files included in the structured application (DTD, read/write rules, formatting template)
        • Structured application
          • Required if you use the structured application for output
          • Collection of files defining how to translate the XML (DTD, Read/Write Rules, Formatting template)
    • 16. Generating Output: Preparation
      • Filter content
        • XML does not filter content
        • Structured application route: you filter content in XSL
        • FrameMaker to WebWorks: requires a conditional text replacement tool that uses structured attributes to define conditional content
          • We use Sourcerer, a FrameMaker plug-in by Advantica:
      • Consider installing an XML editor
        • Allows you to validate your XML
    • 17. Generating Output: XML
      • Copy your structured application file ( to FrameMaker, replacing the existing file
      • Make sure the location of your structured application files match the location defined in the file
        • EDD and structured formatting template
        • DTD
        • Read/write rules: Links the application and the application definition
      • Save your valid FrameMaker file as “XML”
    • 18. Generating Output: XML
      • What do you want to do with your XML?
        • XML imposes no conditions of style
        • XML allows you to generate whatever type of output you need
        • Additional work is required
          • You can convert XML to a deliverable output, such as HTML, using XSL files and an XSL processor, such as Saxon. But this requires you to create the XSL files.
          • If you have an XML schema to associate with the raw XML file, you can open the XML document in Word.
    • 19. Generating Output: WebWorks ePublisher Pro
      • Filter your FrameMaker document
        • Sourcerer
          • Free FrameMaker plug-in
          • Conditional text replacement tool
      • Associate your FrameMaker document with the WWePP project
      • Create a stationary in WebWorks, defining how you want your HTML to look
      • Generate your HTML output
    • 20. Conclusions
      • Structured authoring is not for everyone. Study the implications for your company.
        • Expensive
        • Time-consuming
        • Difficult to learning
      • Structured FrameMaker and Sourcerer
        • You can to move in the XML direction without implementing the full XML workflow
      • If you decide to go with Structure
        • Pre-train
        • Train
        • Plan
        • Test
        • Implement (slowly)
    • 21. Resource Recommendations
      • Publishing Fundamentals: FrameMaker 7 by Sarah O’Keefe and Sheila Loring (formerly published as FrameMaker 7: The Complete Reference )
      • XML Weekend Crash Course by Kay Ethier and Alan Houser
      • Sams Teach Yourself XSLT in 21 Days by Michiel van Otegem
      • Scriptorium White Papers (
        • Integrating XML and FrameMaker
        • Managing Implementations of Structured Authoring
        • XML and Structured Authoring
    • 22. Contact Information
      • Denise Kadilak
      • [email_address]