Publishing Techniques: (Part 2) MadCap Flare – Content Control and Publishing Techniques: (Part 2) Mike Hamilton V.P. Product Management MadCap Software mhamilton@madcapsoftware.com

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

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

Table Style Sheet formatted 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

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

Management Employee Manual Hourly Employee Manual The Old Way Multiple Source Publishing Management Manual Dallas But… We need a version for hourly employees and a version for management. But… We need a version for each of our offices. Management Employee Manual Management Manual Los Angeles Original Draft Employee Manual Hourly Manual Dallas Hourly Employee Manual Hourly Manual Los Angeles

Management Employee Manual Hourly Employee Manual The Old Way Multiple Source Publishing 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 Management Manual Dallas Management Employee Manual Management Manual Los Angeles Original Draft Employee Manual Hourly Manual Dallas Hourly Employee Manual Hourly Manual Los Angeles

Why Single Sourcing? Save Money Save Time Ensure Consistency 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 Target – Enterprise Help Include Enterprise info Exclude Standard info Exclude Print Info Define other specific attributes Enterprise Version Standard Version 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

A library of reusable content 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

A tool for making global updates to all online pages when needed 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

Define page layout options for print deliverables 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

Programmatic Publishing Summary Why use Single-Sourcing Save time and money Ensure consistency Techniques Conditional Markers You 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 Open the WS FTP project Make a copy of the Primary(Master) TOC and name it Print Open the new Print TOC Reorganize the TOC by moving the topic “Online Resources” and the book “Frequent Questions” to the end of the TOC We definitely still have some work to do, first we need a TOC, an Index, and a glossary for our print document. To do that we will look at proxies.

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 In the Content Explorer create a new folder called “Print Topics” Create three new topics, Print TOC, Print Index, and Print Glossary Add the appropriate proxy into each of those topics. Finally add these three new topics to the Print TOC we created earlier.

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 Open the style sheet editor in Advanced View Select “Show Paragraph Styles” and select H1 MAKE SURE TO SELECT THE PRINT MEDIUM! Show students the various options especially the print specific options Make the following changes H1 – in “Font” change to Times New Roman and in “Print Support” change Page Break Before to “Avoid” H2, H3, P – in “Font” change to Times New Roman

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 Create a new sub-class, h1.PageBreak and p.SectionBreak Apply these new styles to the three print support topics In h1.PageBreak in “Print Support” change Page Break Before to “Always” In p.SectionBreak in “Print Support” change Page Break After to “Always”

In Flare 4 USE PAGE LAYOUTS 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 OUT OF DATE In Flare 4 USE PAGE LAYOUTS Create 2 master pages, one for the TOC using little roman numerals and one for the content pages using standard numbers. When the content master page is added to the books of the TOC add the check marks for chapter breaks as well.

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 Create 2 master pages, one for the TOC using little roman numerals and one for the content pages using standard numbers. When the content master page is added to the books of the TOC add the check marks for chapter breaks as well.

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 Update the content master page to use auto-numbering to automatically add chapter numbers to every page.

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 Remove three hyperlinks from the second topic in the TOC and replace them with Cross-References

Suggested Reading List Watch all of the built in Flare tutorial videos. Read as much of the online help overview information as I could handle. Build a couple or three test projects to get a feel for what is going on. Coming from RoboHelp, get a copy of Scott's great book.   MadCap Flare for RoboHelp Users by Scott DeLoach ISBN-13: 978-0615141459  

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