Topic Based Authoring: (Part 1)

Slides:



Advertisements
Similar presentations
Mike Hamilton V.P. Product Management MadCap Software Cascading Style Sheets (Part 3): Images and Text.
Advertisements

MadCap Flare – Controlling Document Look and Feel with CSS
Publishing Techniques: (Part 2)
1 Web-Enabled Decision Support Systems Access Introduction: Touring Access Prof. Name Position (123) University Name.
DOCUMENT TYPES. Digital Documents Converting documents to an electronic format will preserve those documents, but how would such a process be organized?
Using Schoolnet: Creating an Express Test Workshop Mike Antrim Woodbridge Technology Advisory Committee 1.
Microsoft Excel 2010 ® ® Tutorial 6: Managing Multiple Worksheets and Workbooks.
Project 1 Introduction to HTML.
Advanced Technical Writing 2006 Session #3. Today in Class… ► Teams pitch poster concepts:  Meet with your editorial team, show us how your material.
1 CA201 Word Application Creating Document for the Web Week # 9 By Tariq Ibn Aziz Dammam Community college.
1 Computing for Todays Lecture 22 Yumei Huo Fall 2006.
1 of 7 This document is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT. © 2007 Microsoft Corporation.
1 Chapter 11 Developing Custom Help. 11 Chapter Objectives Use HTML to create customized Help topics for an application Use the HTML Help Workshop to.
Developing a Basic Web Page with HTML
Tutorial 11: Connecting to External Data
Mike Hamilton V.P. Product Management
1st Project Introduction to HTML.
Tutorial 3: Adding and Formatting Text. 2 Objectives Session 3.1 Type text into a page Copy text from a document and paste it into a page Check for spelling.
Mike Hamilton V.P. Product Management MadCap Software CasCading Style Sheets (CSS) An introduction and overview.
Sharon Burton Product Manager/Product Evangelist MadCap Software
XP New Perspectives on Microsoft Access 2002 Tutorial 71 Microsoft Access 2002 Tutorial 7 – Integrating Access With the Web and With Other Programs.
WebWorks Publisher An overview Linda G. Gallagher.
Creating Context Sensitive Help Using Single Sourcing
Microsoft Office Word 2013 Expert Microsoft Office Word 2013 Expert Courseware # 3251 Lesson 4: Working with Forms.
HTML 1 Introduction to HTML. 2 Objectives Describe the Internet and its associated key terms Describe the World Wide Web and its associated key terms.
Chapter ONE Introduction to HTML.
Web Design Basic Concepts.
Adobe Dreamweaver CS3 Revealed CHAPTER ONE: GETTING STARTED WITH DREAMWEAVER.
Chapter 4 Dreamweaver: Part II The Web Warrior Guide to Web Design Technologies.
Getting Started with Expression Web 3
Classroom User Training June 29, 2005 Presented by:
XP New Perspectives on Introducing Microsoft Office XP Tutorial 1 1 Introducing Microsoft Office XP Tutorial 1.
1 Lesson 6 Exploring Microsoft Office 2007 Computer Literacy BASICS: A Comprehensive Guide to IC 3, 3 rd Edition Morrison / Wells.
1 Lesson 6 Exploring Microsoft Office 2007 Computer Literacy BASICS: A Comprehensive Guide to IC 3, 3 rd Edition Morrison / Wells.
Using Styles and Style Sheets for Design
INTRODUCTION TO FRONTPAGE. TOPICS TO BE DISCUSSED……….  Introduction Introduction  Features Features  Starting Front Page Starting Front Page  Components.
PowerPoint 2003 – Level 1 Computer Concepts Cathy Horwitz April 25, 2011.
Class Instructor Name Date. Classroom Tips Class Roster – Please Sign In Class Roster – Please Sign In Internet Usage Internet Usage –Breaks and Lunch.
Building Search Portals With SP2013 Search. 2 SharePoint 2013 Search  Introduction  Changes in the Architecture  Result Sources  Query Rules/Result.
Using a Template to Create a Resume and Sharing a Finished Document
HTML, XHTML, and CSS Sixth Edition Chapter 1 Introduction to HTML, XHTML, and CSS.
CIS 205—Web Design & Development Dreamweaver Chapter 1.
Session 1 SESSION 1 Working with Dreamweaver 8.0.
Introduction to HTML Tutorial 1 eXtensible Markup Language (XML)
© 2012 The McGraw-Hill Companies, Inc. All rights reserved. word 2010 Chapter 5 Working with References and Mailings.
10/18/2015 NORTEL NETWORKS CONFIDENTIAL – FOR TRAINING PURPOSES ONLY Global Documentation Evolution System Overview and End-to-End Process Training.
Salt Suite User Guide (Copyright Salt ).
1 Committed to Shaping the Next Generation of IT Experts. Chapter 8 Exchanging Data Between Access and Other Applications Exploring Microsoft Office Access.
1 Introduction  Extensible Markup Language (XML) –Uses tags to describe the structure of a document –Simplifies the process of sharing information –Extensible.
Microsoft ® Office Excel 2003 Training Using XML in Excel SynAppSys Educational Services presents:
Advanced Technical Writing 2006 Session #4. Today in Class… ► Meet with your editorial team, refine/post deliverables ► Send URL for deliverables to Bill.
FIRST COURSE PowerPoint Tutorial 4 Integrating PowerPoint with Other Programs and Collaborating with Workgroups.
HTML Concepts and Techniques Fifth Edition Chapter 1 Introduction to HTML.
Word Create a basic TOC. Course contents Overview: table of contents basics Lesson 1: About tables of contents Lesson 2: Format your table of contents.
Chapter 1 Introduction to HTML, XHTML, and CSS HTML5 & CSS 7 th Edition.
Chapter 29. Copyright 2003, Paradigm Publishing Inc. CHAPTER 29 BACKNEXTEND 29-2 LINKS TO OBJECTIVES Attach an XML Schema Attach an XML Schema Load XML.
Introduction. Internet Worldwide collection of computers and computer networks that link people to businesses, governmental agencies, educational institutions,
Academic Computing Services 2007 Microsoft Word 2010 Publishing Long Documents This Guide will teach you how to work with long documents such as dissertations.
XP Creating Web Pages with Microsoft Office
Web Page Programming Terms. Chapter 1 Objectives Describe Internet and Understand Key terms Describe World Wide Web and its Key terms Identify types and.
HTML PROJECT #1 Project 1 Introduction to HTML. HTML Project 1: Introduction to HTML 2 Project Objectives 1.Describe the Internet and its associated key.
Microsoft FrontPage 2003 Illustrated Complete Creating a Web Site.
Lesson 11 Exploring Microsoft Office 2007
Project 1 Introduction to HTML.
Mike Hamilton V.P. Product Management MadCap Software
Project 1 Introduction to HTML.
Manager, IT Training and Documentation
Microsoft® Office Word 2007 Training
Tutorial 7 – Integrating Access With the Web and With Other Programs
Microsoft Office Illustrated Fundamentals
Presentation transcript:

Topic Based Authoring: (Part 1) MadCap Flare – An Introduction to Topic Based Authoring: (Part 1) 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 Definitions Flare overview – Architecture and differences Flare interface tour New project guidelines Creating projects – Frame/Word/Robo/Template/DITA Adding content to existing projects – New Topics/ Word/Frame/DITA/media Primary Navigation TOC/Index/Search

Terms and Definitions

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

Topic-based authoring 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. Very supportive of User focused product development

Single-source publishing 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.

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

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

Multi-channel publishing 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: The content files (the actual XML files) The rules (Schema files) 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 Overview: Architecture and differences from other tools

Flare Project Architecture Project Directory Content Folder Output Folder Project Folder ProjectName.flprj

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

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

Flare Project Architecture Project Directory Content Folder Output Folder Project Folder ProjectName.flprj The Project Folder stores all of the advanced single-sourcing and project level files Conditions Variables Publishing data More…

Flare Project Architecture Project Directory Content Folder Output Folder Project Folder ProjectName.flprj 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 – There is no hidden database Flare projects can be stored locally on your PC or they can be stored on a network 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.

Forget what you know from previous tools! 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.

Example – RoboHelp Word Import 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

Example – WWP and Framemaker 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

Flare Interface Tour (Live Demo)

New Project Guidelines

Who is the target audience? What are their needs? Project Planning Plan before you begin! Who is the target audience? What are their needs? What is the scope of the project? How many deliverables? Once these questions are answered, get buy in from all stakeholders

Once the high level questions are addressed, where do you begin? Project Planning Once the high level questions are addressed, where do you begin? More planning! What specific content needs to be written?

Remember – Think Topics About Programming Objects and Inheritance Editing Reports Containing Objects Relating Objects Project Adding Users Setting Permissions Deleting Users Placing Objects Importing Reports Setting Schedules About Reports About Objects About Users Exporting Objects About Containment Customizing Objects Printing Reports Using Container Objects Saving reports Creating Reports About Schedules

Remember – Think Topics Project Admin Guide About Users Adding Users Deleting Users Setting Permissions About Reports Creating Reports Editing Reports Saving Reports Printing Reports Importing Reports Programmers Guide About Programming About Objects Placing Objects About Containment Objects and Inheritance Using Container Objects Customizing Objects Relating Objects Getting Started Exporting Objects About Schedules

How do I know what topics I need? Identify all the tasks the user needs to accomplish What do they need to do? concept info they need for each task What do they need to understand to do it? reference info they need for each task What do they need to know while they do it?

Flare Power Tip! At the beginning of a project bring key staff together for brainstorming Brainstorm the various tasks customers will need to accomplish Open Flare and create a new Table of Contents As tasks are identified capture them by adding a new TOC page in Flare No need to manually transcribe later!

Creating Projects

Creating a Flare Project Flare projects can be created from: Flare templates Your custom templates Microsoft Word or Framemaker documents RoboHelp HTML projects DITA content (announced today!)

Show Various Project Creation Methods (Live Demo)

Adding Content to Projects

Creating a New Topic To create a topic: 1 Select a folder in the Content Explorer. 2 Click in the Content Explorer toolbar. —OR— Select Project > Add Topic. Right-click the Content folder and select Add Topic. The Add New Topic dialog appears.

Creating a New Topic

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 During Import Do Not Preserve 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

Adding Graphic/Media Content To insert an image: 1 Open a topic. 2 In the XML Editor, place your insertion point cursor where you want to insert the picture. 3 Click in the XML Editor toolbar. —OR— Select Insert > Picture. The Insert Picture dialog box appears.

Adding Graphic/Media Content

Live Image Editing Using MadCap Capture (Live Demo)

Adding Navigation

Three primary navigation tools Table of Contents Index Search Adding Navigation Three primary navigation tools Table of Contents Index Search

Creating a Table of Contents (TOC) A TOC is constructed of two representations Books Act as “containers” and provide navigation to large sets of information May or may not also act as links to topics Pages Provide links to your topics

Creating a Table of Contents (TOC)

Remember – Think Topics A TOC determines which topics are published, and in what order, for any given output.

Index Indexing is the art and science of making information accessible through the use of keywords Each keyword provides a shorter list of more relevant topics than would be returned when searching for the same keyword in the full-text search. It lets users know what keywords are relevant in the product. It converts to an index in print documentation. Beginner to intermediate users with specific questions may have the best chance of finding the answer to their question quickly by starting with the index.

Go beyond the terms in your text Indexing in Flare Go beyond the terms in your text Include synonyms or phrases your readers would likely use to look up information Be consistent: Do you say “insert” (infinitive) or “inserting” (participle)? Do you say “picture” (singular) or “pictures” (plural)? Do you capitalize the terms (Inserting a picture, inserting a picture, or Inserting a Picture)? Do you include phrases (inserting a picture)? Do you create sub-keywords?

Place the cursor in the text you want to index Indexing in Flare Place the cursor in the text you want to index F10 – Adds the word from your topic to your index F9 – Opens the Index Entry dialog and allows you to enter synonyms

Search Built automatically You can augment/improve search results by creating good index keywords Search result ranking based on: Number of times search term appears Where it appears (headings, body,…) Indexing

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