View
222
Download
0
Category
Tags:
Preview:
Citation preview
Mike HamiltonV.P. Product ManagementMadCap Softwaremhamilton@madcapsoftware.com
MadCap Flare – Content Control and Publishing Techniques: (Part 2)
Slides
Slides are available on Mike’s blog at:
http://madcapsoftware2.wordpress.com
Agenda
• Welcome/introductions • Load files on laptops/Skill survey• Tables• Conditional Markers• Variables• Snippets• Multiple TOCs• Master Pages/Page Layouts• Mediums in CSS• Publishing Targets• Programmatic Publishing• Print publishing in depth
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 WayMultiple Source Publishing
Original Draft
EmployeeManual
Hourly Employee Manual
Management Employee Manual
Management Manual Dallas
Management Manual Los Angeles
Hourly Manual Dallas
Hourly Manual Los Angeles
But…
We need a version for hourly employees
and a version for management.
But…
We need a version for each of our
offices.
The Old WayMultiple Source Publishing
Original Draft
EmployeeManual
Hourly Employee Manual
Management Employee Manual
Management Manual Dallas
Management Manual Los Angeles
Hourly Manual Dallas
Hourly Manual Los Angeles
•Inconsistency
•It is very easy to miss an edit in one or more versions.
•The result is inconsistent information going to your customers
•Expense
•The edits that should only need to be done once must be performed multiple times on multiple versions
•This costs more than it should
•This takes longer than it should
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 Master
Source Files
Add Conditional
Tags/Variables
Define Publishing
Targets
Generate Output
Print Only
Enterprise Version
Standard Version
Target – Enterprise Help • Include Enterprise info• Exclude Standard info• Exclude Print Info• Define other specific
attributes
Target – Standard Print • Include Standard info• Include Print info• Exclude Enterprise info• Define other specific
attributes
Target – Standard Help • Include Standard info• Exclude Enterprise info• Exclude Print 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 online pages when needed– Add headers and/or footers
– Add copyright information
– Add navigation elements like “Breadcrumb” trails
Page Layouts
• Define page layout options for print deliverables
• Headers/footers, variables and so on
– Highly customizable
• Assign the “type” of page
– Right, Left, Title, Normal, and Empty
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 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
• TechniquesConditional
MarkersYou know the content in advance
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 Publishing
Build documentation programmatically from the 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
• Page Layouts–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
Page Layouts
Page Layouts provide you with page level and section/chapter level formatting
•Each Page Layout can contain separate layout pages for start, odd, even and empty 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
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. Coming from RoboHelp, get a copy of Scott's great book.
MadCap Flare for RoboHelp Users by Scott DeLoachISBN-13: 978-0615141459
Suggested Reading List
HTML, XHTML, and CSS, Sixth Edition (Visual Quickstart Guide)by Elizabeth CastroISBN-13: 978-0-321-43084-7 Technical Writing 101: A Real-World Guide to Planning and Writing
Technical Documentationby Alan S. Pringle and Sarah O'KeefeISBN-13: 978-0970473325 CSS: The Definitive Guide, Second Edition by Eric MeyerISBN-13: 978-0596527334 DHTML and CSS for the World Wide Web, Third Edition (Visual Quickstart
Guide)by Jason TeagueISBN-13: 978-0-201-73084-5
Questions?
Thank You!
Mike HamiltonV.P. Product ManagementMadCap Softwaremhamilton@madcapsoftware.com
Recommended