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

1,733

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

0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
1,733
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
0
Comments
0
Likes
1
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. 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: http://my.advantica.biz/sourcerer/
      • Consider installing an XML editor
        • Allows you to validate your XML
    • 17. Generating Output: XML
      • Copy your structured application file (structapps.fm) to FrameMaker, replacing the existing structapps.fm file
      • Make sure the location of your structured application files match the location defined in the structapps.fm 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 (http://www.scriptorium.com/papers.html)
        • Integrating XML and FrameMaker
        • Managing Implementations of Structured Authoring
        • XML and Structured Authoring
    • 22. Contact Information
      • Denise Kadilak
      • [email_address]

    ×