Single Sourcing

Document Sample
Single Sourcing Powered By Docstoc
					Mike Hamilton
V.P. Product Management        The session will start
MadCap Software                3 minutes after the hour
mhamilton@madcapsoftware.com
              Welcome!




Mike Hamilton
V.P. Product Management
MadCap Software
mhamilton@madcapsoftware.com
                                       Agenda
 9:00-9:20    Flare Overview: Differences
                with other tools
 9:20-9:45    Importing Word/FrameMaker
 9:45-10:15   Tables: Creation, editing, and
                styles
10:15-11:00   Single-sourcing Techniques
11:00-11:10   Break
11:10-12:25   Print Publishing
12:25-1:00    Context Sensitive Help
Flare Overview:
Architecture and differences
from other tools
                             Terminology


• Topic-based authoring
• Single-sourcing
• Multi-channel publishing
• XML
• Project
                                          Terminology

Topic-based authoring
From Wikipedia, the free encyclopedia



Topic-based authoring is a modular content creation
  approach (popular in the technical publications and
  documentation arenas) that supports XML content
  reuse, content management, and makes the dynamic
  assembly of personalized information possible.
A topic is a discrete piece of content that is about a
  specific subject, has an identifiable purpose, and can
  stand alone (does not need to be presented in context
  for the end-user to make sense of the content). Topics
  are also reusable. They can, when constructed properly
  (without reliance on other content for its meaning), be
  reused in any context anywhere needed.
                                                                          Terminology

Single-source publishing
From STC publication Beyond the Buzzword: Single-sourcing, Sean Brierly


Single sourcing is a documentation workflow that
   creates multiple deliverables from one unmodified
   source document - that is, in the process of
   creating the deliverables, the source document is
   not edited or modified.
If you produce multiple deliverables that share some
   of the same content, single sourcing can reduce
   the resources in time and staff you need to produce
   them. Single sourcing really begins to shine when
   it’s time to edit and update the deliverables,
   because all the changes can be made to a single
   document.
                                                               Terminology

Multi-channel publishing
From Mike Hamilton, V.P. Product Management, MadCap Software



Multi-channel publishing is to delivery formats as
 Single-sourcing is to content. Where Single-source
 publishing is flexibility in the re-use of content, Multi-
 channel publishing is flexibility in the publishing and
 distribution of that content to various modalities or
 media types, such as print (paper), print (electronic),
 web, computer desktop, or other.
                                        Terminology

XML
From Wikipedia, the free encyclopedia


The Extensible Markup Language (XML) is a
   general-purpose markup language. Its primary
   purpose is to facilitate the sharing of structured
   data across different information systems.
It started as a simplified subset of the Standard
   Generalized Markup Language (SGML), and is
   designed to be relatively human-legible. By adding
   semantic constraints, application languages can be
   implemented in XML. These include XHTML and
   thousands of others.
                                                               Terminology

XML
From Mike Hamilton, V.P. Product Management, MadCap Software




A proper XML work flow that works with well-formed
  and valid files has three requirements:
1. The content files (the actual XML files)
2. The rules (Schema files)
3. The publishing conversions (transforms)
                                             Terminology

Project
A Flare project is a collection of all of the files needed for
  the authoring and publishing process. These include the
  content files (topics), images, Cascading Style Sheet
  (CSS) files, templates, and more.
Not every file in a Flare project is necessarily used in
  generating the deliverables that you create. Collectively
  these files become your “palette” of available options for
  creating very specific documents for specific publishing
  needs.
      Flare Project Architecture


Project Directory

   Content Folder



   Output Folder



   Project Folder



  ProjectName.flprj
                      Flare Project Architecture


Project Directory

   Content Folder
                         • The Content Folder stores all
                           of the information you import
                           or create. Topic files, images,
   Output Folder           etc.
                         • The Content Folder also
                           stores files which control the
   Project Folder          look of the content.
                           Cascading Style Sheets,
                           Master Pages, etc.
  ProjectName.flprj
                      Flare Project Architecture


Project Directory

                         • The Output Folder is the
   Content Folder          default location where
                           documents you publish will
                           be stored.
                         • If you publish, or generate,
   Output Folder
                           four different “outputs” then
                           each of these will be found in
                           this folder, each in their own
   Project Folder          subfolder.


  ProjectName.flprj
                      Flare Project Architecture


Project Directory

   Content Folder
                         The Project Folder stores all of
                         the advanced single-sourcing
                         and project level files
   Output Folder
                         • Conditions
                         • Variables
                         • Publishing data
   Project Folder        • More…


  ProjectName.flprj
Flare Project Architecture




   • The main project file is also
     in this directory with a .flprj
     extension.
   • The main project file is
     simply an XML file with high
     level project information
     recorded to coordinate all of
     the other project files.
                        Flare Architecture Key Points
Attribute                Benefit

A Flat File structure – Flare projects can be stored locally on your
There is no hidden      PC or they can be stored on a network
database                drive without fear of database corruption
                        that plagues tools with older architectures.

XML files exclusively    All Flare files, not just content but also
                         project files, are standard XML files. There
                         are no hidden, proprietary, or binary files.
                         This allows complete project transparency
                         and access to all content and data, even
                         from external tools.

Unicode support          The Flare editor and architecture are
                         compatible with industry standards making
                         it much easier to localize content if or when
                         necessary.
                         Important Concepts

Forget what you know from
previous tools!
 OK, perhaps that is a little harsh, but Flare
 has been built from the ground up to
 support single-sourcing so many of its
 capabilities are more granular and flexible
 than items presented in Wizards in other
 tools.
 Many problems new users have are from
 trying to do things in Flare “the old way”
 that they did them in previous tools.
                      Important Concepts

Example – RoboHelp Word Import
 – A wizard driven, one step process
 – Must be repeated every time a document
   is imported
Flare Word Import
 – A TWO step process
 – First define the import rules and save
   them as a reusable file
 – Then import the actual Word document(s)
   using the import rules file
                            Important Concepts

Example – WWP and Framemaker
 – Uses a single template to control all
   conversion and publishing
 – Can use this template to go straight from
   Framemaker directly to published output
Flare and Framemaker
 – Can also go straight from Frame to
   published output BUT what is a single
   template in WWP is two files in Flare
   • The import rules
   • The publishing rules
Importing Content:
Microsoft Word
FrameMaker
 Leveraging Word and FrameMaker Content


Process
• Select documents to import
• Determine topic break points
• Choose import options
• Style sheet import/creation
• Style mapping
 Leveraging Word and FrameMaker Content



Two key items
• Style handling during import
• Which workflow to choose
   – “EasySync”
   – Single Import
   Leveraging Word and FrameMaker Content

Style handling during import
• The key decision – to Preserve Styles
  or not




• This will impact how styles will be
  named in the Flare project
   Leveraging Word and FrameMaker Content

Style handling during import
  Preserve Styles      Do Not Preserve
  During Import      Styles During Import
  Leveraging Word and FrameMaker Content

Which workflow to choose
• Single Import
   – Leverage completed documents
   – Imported content can be edited freely
     within the Flare editor
• “EasySync”
   – Leverage “live” documents
   – The source editor (Word or
     FrameMaker) should be used for all
     content edits
Tables:
Creating, editing, styles
                               Tables

• Creating a Table
• Table formatting using CSS
• Table editing
• Advanced table techniques
                                Tables

Two types of tables
• Inline formatted
• Table Style Sheet formatted
                     Inline Formatted Tables

Pros
• Complete formatting control
• Most flexibility
• Best for complex tables
Cons
• Can be a challenge for single-sourcing
• Can not be controlled from a central
  style sheet
               Style Sheet Formatted Tables

Pros
• Hundreds of tables can be centrally
  controlled
• Extremely powerful with
  conditionals/single-sourcing
• Best for simple tables
Cons
• Styles can get complex
• Requires practice/experimentation
                               Tables

• What parts of a table should be
  controlled where?
• “TD” and “TH” elements
• The “P” element trick
Single Sourcing
                                Overview


• What is Single-Sourcing?

• Why Use Single-Sourcing?

• How to Build a Single-Source Work Flow

• Summary
                                            The Old Way
               Multiple Source Publishing

                                            Management Manual
                                                  Dallas
                     But…
                      But…
                   Management
                    Employee                Management Manual
               We need version
              We need aa version
                     Manual                    Los Angeles

 Original   for hourly employees
                 for each of our
  Draft
Employee              version
              and a offices. for              Hourly Manual
 Manual
                management.                      Dallas

                    Hourly
                   Employee
                    Manual                    Hourly Manual
                                               Los Angeles
                                                    The Old Way
                   Multiple Source Publishing

            •Inconsistency                          Management Manual
                                                          Dallas
               • It is very easy to miss an edit in one or more
                 versions.
                        Management
               • The result is inconsistent information going to
                         Employee                 Management Manual
                 your customers
                           Manual                      Los Angeles
            •Expense
 Original
  Draft        • The edits that should only need to be done
Employee         once must be performed multiple times onManual
                                                    Hourly
 Manual          multiple versions                      Dallas

                            more
               • This costsHourly than it should
                        Employee
               • This takes longer than it should
                         Manual                       Hourly Manual
                                                       Los Angeles
                  Why Single Sourcing?

• Save Money
  – The same documentation can be
    maintained with single edits instead of
    multiple edits
  – This means fewer editing hours
• Save Time
  – Fewer edits mean less time editing
  – Documents can be published on demand
• Ensure Consistency
  – One place to make edits
  – No multiple-handling of documents
             How Can Software Help?


• By providing a set of features that
  facilitates a simple, intuitive
  process for creating a set of all-
  inclusive master documents while
  allowing content to be identified as
  being unique for any publishing
  purpose
                                                          The Process
  Create            Add                          Define
                                                                   Generate
  Master         Conditional                   Publishing
                                                                    Output
Source Files   Tags/Variables                   Targets


                          Enterprise   Target – Enterprise Help
                          Version      • Include Enterprise info
                          Standard     • Exclude Standard info
                          Version      • Exclude Print Info
                                       • Define other specific
                                         attributes

                          Print Only   Target – Standard Help
                                       • Include Standard info
                                       • Exclude Enterprise info
                                       • Exclude Print Info
                                       • Define other specific
                                         attributes

                                       Target – Standard Print
                                       • Include Standard info
                                       • Include Print info
                                       • Exclude Enterprise info
                                       • Define other specific
                                         attributes
         Techniques for Single Sourcing


• Conditional Markers
• Variables
• Snippets
• Multiple TOCs
• Master Pages
• Mediums in CSS
• Publishing Targets
• Programmatic Publishing
         Techniques for Single Sourcing


• Conditional Markers
• Variables
• Snippets
• Multiple TOCs
• Master Pages
• Mediums in CSS
• Publishing Targets
• Programmatic Publishing
                           Conditional Marker

• Identify any content or asset as being
  unique for any reason
  –   Audience (basic, advanced, language etc.)
  –   Publishing media (print, desktop, web)
  –   Version (standard, enterprise)
  –   Work flow (in progress, ready for review)
• Apply at the character, sentence,
  paragraph, page, or file level
• Apply to any element (graphics, tables,
  etc.)
• A great tool when you know the content in
  advance
Conditional Marker
         Techniques for Single Sourcing


• Conditional Markers
• Variables
• Snippets
• Multiple TOCs
• Master Pages
• Mediums in CSS
• Publishing Targets
• Programmatic Publishing
                                  Variables

• The technique to use when you know
  where the content needs to go, but
  you won’t know the content until you
  publish
• Great for
  – Feature names for software
  – Personalization (i.e. customer names)
  – Employee contact information
  – Any data that may change between
    when you write and when you publish
Variables
         Techniques for Single Sourcing


• Conditional Markers
• Variables
• Snippets
• Multiple TOCs
• Master Pages
• Mediums in CSS
• Publishing Targets
• Programmatic Publishing
                                   Snippets

• A library of reusable content
• Can contain any content from a few
  characters to full pages of information
• Can contain text, tables, images, or
  any other content
• Great for
  – Warnings, Cautions
  – Common procedure steps
  – Legal information such as copyright
  – Any content used in multiple places
    throughout the documentation
Snippets
         Techniques for Single Sourcing


• Conditional Markers
• Variables
• Snippets
• Multiple TOCs
• Master Pages
• Mediums in CSS
• Publishing Targets
• Programmatic Publishing
                           Multiple TOCs

• Tailor a custom Table of Contents for
  any need or audience and save them
  all to the project
• A different TOC can be created for
  different delivery formats (online vs.
  print) or for different audiences
  (different language TOCs)
• Or a master TOC can be customized
  automatically using Conditional
  Markers within the TOC
Multiple TOCs
         Techniques for Single Sourcing


• Conditional Markers
• Variables
• Snippets
• Multiple TOCs
• Master Pages
• Mediums in CSS
• Publishing Targets
• Programmatic Publishing
                                Master Pages
• A tool for making global updates to all
  pages when needed
  – Add headers and/or footers
  – Add copyright information
  – Add navigation elements like
    “Breadcrumb” trails
  – Define page layout options for print
    deliverables
• A single Master Page can be used or
  separate master pages can be used
  for unique chapter formatting
Master Pages
         Techniques for Single Sourcing


• Conditional Markers
• Variables
• Snippets
• Multiple TOCs
• Master Pages
• Mediums in CSS
• Publishing Targets
• Programmatic Publishing
                             Media Types

• A CSS technique that allows multiple
  style definitions for the same element
  but within a single style sheet
• The Media Type assigned determines
  which style definition will be used for
  a given Publishing Target
• You can define a single style sheet to
  support all of your publishing needs
Media Types
         Techniques for Single Sourcing


• Conditional Markers
• Variables
• Snippets
• Multiple TOCs
• Master Pages
• Mediums in CSS
• Publishing Targets
• Programmatic Publishing
                          Publishing Targets

• The key piece for single-sourcing
• A Publishing Target stores all of the
  attributes that make a document unique
  – What conditions to include/exclude
  – What variables to override
  – What TOC to include
  – Etc.

• You should create a separate Publishing
  Target for every deliverable you have to
  provide
Publishing Targets
         Techniques for Single Sourcing


• Conditional Markers
• Variables
• Snippets
• Multiple TOCs
• Master Pages
• Mediums in CSS
• Publishing Targets
• Programmatic Publishing
             Programmatic Publishing

• Any document defined by a Publishing
  Target can be built programmatically
  from a command line interface
• Documentation can be built “just in
  time” using this model
• Documentation can also be scheduled
  and scripted for building during off
  peak hours
             Programmatic Publishing




cd\program files\madcap software\madcap
flare v2.5\flare.app
madbuild –project
c:\MyProjectFolder\MyProject.flprj
–target WebHelp
                                                           Summary
• Why use Single-Sourcing
  – Save time and money
  – Ensure consistency
• Techniques
     Conditional       You know the content in advance
      Markers
      Variables        When the content may change
      Snippets         Reusable content library
    Multiple TOCs      As many as necessary for publishing needs
    Master Pages       Global updates to all pages published
    CSS Mediums        Support all deliverable formatting in a single style
                       sheet

  Publishing Targets   Define the different documents you need to deliver

    Programmatic       Build documentation programmatically from the
      Publishing       command line or scheduled script
Print Publishing
                                Print Publishing

• Creating a print TOC – controlling the order of
  content
• Proxies – The way to get print TOC, Index, and
  Glossary generated automatically
• Using the Medium option to tailor a CSS to
  support print publishing – control the look/feel of
  content
• Master Pages – controlling page layout
• Cross References – links designed to support print
  publishing
• Auto-numbering – The key to numbering for all
  things beyond lists
                      Creating a print TOC
Why create a separate TOC for your print
outputs?
• Complete control, not just of what
  information is included but on the exact
  order of the topics.
• Eliminate topics referenced more than
  once. While this is common for online, it is
  a bit odd for print.
OK, we have a custom print TOC, what kind
of document does this give us?
                     Link
                        Including Proxies
A Proxy is just a place holder. You insert a
proxy wherever you want a print TOC, Index,
or Glossary with automatically generated
page number references.
• Create new topics to contain your proxies
• Add proxies to the new topics
• Link to the new proxy topics from your TOC
We have added everything necessary for an
automatically updated TOC, Index, and
Glossary in our print document.
                      Link
            Using CSS Medium Settings
The styles used for online are not usually
optimal for a print experience. CSS Mediums
allow for adjusting style properties.
• Change text properties
• Control backgrounds
• Adjust where page breaks occur
  automatically
Now with adjusted CSS properties our
document is really looking close to
publishing.
                     Link
              Using CSS Medium Settings
The document is looking better, but the CSS
changes have caused our TOC, Index, and Glossary
to flow together with the topics.
• It would be tempting to add some page breaks in
  the Word document, but we don’t want this kind
  of post processing
• We will create two sub class styles in Flare, one
  for H1 styles and one for P styles
• This will give us control over the page break
  locations while keeping a single-source work flow
Now with adjusted CSS properties our document is
really looking close to publishing.
                          Link
                                   Master Pages
Master Pages provide you with page level
and section/chapter level formatting
• Start, odd, and even page formatting
  including headers and footers
• Two different ways to implement:
  – At the publishing target (quick, easy)
  – At the TOC (much more powerful)




                       Link
                           Auto-Numbering
Auto-Numbering can be used to allow for
automated figure or table numbers, for
government style paragraph numbering, or
for automatically generating chapter
numbers
• Create a custom style class
• Add auto-numbering to the style class
• Use the new style class in the Master Page


                    Link
                             Cross-References
Cross-references allow for an extremely
elegant single-source handling of linking
• Controlled by CSS
• Can look like standard hyperlinks for online
  publishing
• Converted to proper page number
  references when going to print


                      Link
Context Sensitive Help
                         Overview



• The Three Key Pieces

• The Microsoft Model

• Implementation
                The Three Key Pieces

Context sensitive help relies on
three key pieces of information

    –Topic ID
    –Map Number
    –Topic File Name
                 The Three Key Pieces


Topic ID
• The Topic ID is a text string to help
  the programmer in making the call
  from the application to the correct
  Help topic
• Can usually be identified by a prefix
  such as ID_ or IDD_
                The Three Key Pieces


Map Number
• The Map Number is just a number,
  nothing special
• This number is used by the
  program to identify and call the
  correct Help topic
                 The Three Key Pieces


Topic File Name
• The Topic File Name is the actual
  name of the physical .htm file
  that is a topic in the Help system
              Window Level Help Model

The software user makes a “Help
Call” by pressing the F1 key



                Help Call

Application

                            MS Windows
                            Help Viewer
                       Window Level Help Model

Details of Help Call sent from App


     hwndCaller                                 uCommand
Call to HTML Help viewer             Defines Help display properties
                           Help Call
HWND HtmlHelp(Hwnd, “C:\path\sample.chm”, HH_HELP_CONTEXT, 1003);

Application                pszFile                          dwData
                   Name and path for CHM file             Map Number
                                                    MS Windows
                                                    Help Viewer
              Window Level Help Model

The software user makes a “Help
Call” by pressing the F1 key



                Help Call

Application

                            MS Windows
                            Help Viewer
              Window Level Help Model
The Help Viewer looks for a “Map
File” compiled into the .CHM file




MS Windows
Help Viewer
              Window Level Help Model
The Help Viewer uses this Map File
to match the Map Number to a Topic
ID




MS Windows
Help Viewer
               Window Level Help Model
The Help Viewer then opens an “Alias
File” compiled within the .CHM




 MS Windows
 Help Viewer
              Window Level Help Model
The Help Viewer uses this Alias List
to match the Topic ID to a Topic File
Name




MS Windows
Help Viewer
              Window Level Help Model

The Help topic is displayed




MS Windows
Help Viewer
Window Level Help Model
Creating
 Context Sensitive Help
                  in Flare
     Creating Context Sensitive Help
Adding the map/header file
Creating Context Sensitive Help
Creating Context Sensitive Help
     Creating Context Sensitive Help
Topic IDs and Map Numbers
     Creating Context Sensitive Help
Assigning Topics
     Creating Context Sensitive Help
Assigning Topics
Creating Context Sensitive Help
     Creating Context Sensitive Help
Skin Support for WebHelp
         Mike’s Suggested Reading List
1. Watch all of the built in Flare tutorial videos.

2. Read as much of the online help overview
   information as I could handle.

3. Build a couple or three test projects to get a
   feel for what is going on.

4. If I were coming from RoboHelp I would get a
   copy of Scott's great book.

         MadCap Flare for RoboHelp Users
         by Scott DeLoach
         ISBN-13: 978-0615141459
    Mike’s Suggested Reading List

HTML, XHTML, and CSS, Sixth Edition (Visual Quickstart Guide)
by Elizabeth Castro
ISBN-13: 978-0-321-43084-7

Technical Writing 101: A Real-World Guide to Planning and Writing
   Technical Documentation
by Alan S. Pringle and Sarah O'Keefe
ISBN-13: 978-0970473325

CSS: The Definitive Guide, Second Edition
by Eric Meyer
ISBN-13: 978-0596527334

DHTML and CSS for the World Wide Web, Third Edition (Visual Quickstart
    Guide)
by Jason Teague
ISBN-13: 978-0-201-73084-5
Questions?
            Thank You!




Mike Hamilton
V.P. Product Management
MadCap Software
mhamilton@madcapsoftware.com

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:9
posted:2/16/2012
language:English
pages:103