mike hamilton v.p. product management madcap software [email protected] madcap flare –...

Mike HamiltonV.P. Product ManagementMadCap [email protected]

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

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

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

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

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

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

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

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

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


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


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 [email protected]

mike hamilton v.p. product management madcap software [email protected] madcap flare –...

Documents

single sourcing slide

publishing purpose slide

documentation slide

depth slide

practiceexperimentation

advance slide

conditional marker slide

publishing techniques