DITA Quick Start Webinar: Defining Your Style Sheet Requirements


Published on

Your DITA implementation is under way, and promises higher content reusability with shorter time to publication. A key aspect of your implementation is automated multi-channel publishing of your content to a variety of outputs: PDF, HTML, online help, mobile, dynamic web, eLearning and more. In this webinar, expert project manager Yehudit Lindblom and Suite Solutions President Joe Gelb go beyond formatting requirements to review best practices that help you cover all the bases for smooth implementation and easy maintenance of your dynamic publishing customizations.
Learn more about DITA Quick Start http://www.suite-sol.com/pages/solutions/dita-quick-start.html
Follow us on LinkedIn http://www.linkedin.com/company/527916

Published in: Technology
1 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

DITA Quick Start Webinar: Defining Your Style Sheet Requirements

  1. 1. DITA Quick Start: Defining Style Sheet Requirements Yehudit Lindblom & Joe Gelb January 21, 2014
  2. 2. Who are we? Yehudit Lindblom • Project Manager and cat herder Joe Gelb • Founder and President of Suite Solutions Suite Solutions Our Vision: Enable you to engage your customers by providing quick access to relevant information: DITA provides the foundation • Help companies get it right the first time • XML-based Authoring/Publishing Solutions • Enterprise Intelligent Dynamic Content: SuiteShare Social KB • Consultancy, Systems Integration, Application Development • Cross-Industry Expertise • High Tech, Aerospace & Defense, Discrete Manufacturing • Healthcare, Government
  3. 3. Main Topics  Goals of this webinar  The Magic Button: high quality, localized output from DITA  Common Requirements  PDF  HTML  Online Help  ePUB  Mobile  Localization Considerations
  4. 4. Goals of this Webinar Primary Goal: Empower (not overwhelm) you • Understand the process, details and dependencies involved • Understand the possibilities • Help to avoid making assumptions… • Manage expectations
  5. 5. Key Components of a DITA Solution 1. 2. 3. 4. 5. Staff Content Translation Publishing Content and configuration management Your mission is to develop or acquire each of these
  6. 6. The Magic Button • • Common misconceptions about DITA • DITA publishing can't match the quality and complexity of desktop publishing • Loss of control over the final output as with tools like FM and InDesign [ those last minute tweaks, page-breaks…. ] The reality • Anything we’ve seen can be done using DITA publishing • Style sheets can be customized, parameterized, localized • CMS + style sheets gives you the Magic Button: any format in any language for any device • Well…. Not so easy at first: takes effort to set it all up
  7. 7. Multi-purpose Publishing • • Single-source, many outputs • PDF: hi-fidelity vs online, manuals, data sheets, fold-outs, labels… • Help: CHM, Web Help, HTML5, website, KB, man pages … • Mobile: ePUB, Mobi, Nook, feeding native apps, responsive design… • InDesign • Word • Integrations with other systems: Salesforce, Jive… Dynamic Web Publishing: content on-demand
  8. 8. Content, Structure, Presentation • Document Type Definition (DTD) • Schema Structure Rules Document Instance • XML • Media, graphics Presentation Rules (Style Sheet) Presentation • • • • XSL XSL-FO CSS Shakespearean Templates • • • • • • • PDF HTML ePUB DOCX InDesign SVG …
  9. 9. Typical DITA Toolset XML Authoring SME Review CMS Content Management System Automated Publishing - DITA Open Toolkit - DITA Accelerator Web Help Dynamic Web - SuiteShare - LiveContent Reach - DITA Web - Fluid Topics Help Manuals Mobile On-demand
  10. 10. High Level Process 1. Assembling your project team • Project manager, at least one author, and perhaps a graphic designer (and they all might be the same person) 2. Building requirements • Which outputs do you have now? What do you want to add or change? • Opportunity to implement new formats your customers are asking for 3. Information Architecture • How are your DITA elements being used? • What output do you want from them? 4. Solution Architecture: CMS, publishing tools 5. Style sheet development 6. Deployment 7. Support / Tweaks
  11. 11. Be Prepared • • • • • Your project team will need to make nitty-gritty detailed decisions about requirements and priorities It is important to set as many requirements as possible before the development starts • Avoids scheduling or budget surprises, cost overruns Identify detailed formatting requirements for each output format: • PDF, HTML, help, mobile, dynamic web, eLearning… Coordinate with the information architect and conversion team Communicate clear and detailed formatting requirements to your vendor
  12. 12. Be Prepared • • • Have all the fonts available before start Test Data • Invest the time to put together good representative test data • Should be based on your IA • Simulate each combination of tagging and structure • Test data should be representative of actual XML exported from the CMS during publishing Build time for review into your schedule • You need to review your new outputs thoroughly • Better to be realistic and allot more time than to do a quick review and miss issues
  13. 13. Testing and Revisions • • • • Job isn’t finished until you can publish real content from the CMS • Ideally, even for beta testing, publish converted content from the CMS Localized style sheets cannot be completed until tested with real translated content Leave room in your budget for tweaking the style sheets As you migrate more content, you will encounter new patterns in the tagging • Style sheets are very sensitive to differences in tagging, especially for PDF • Page-break rules are sometimes complex and may be tweaked over time
  14. 14. Basic Requirements for all outputs • • Content-based rules, for example: • Task steps: if only 1 step, style as a paragraph; if >1, style as list • Reordering pre-requisite and context (use general task type instead) Basic formatting: fonts, colors, sizes, spacing… Reality Check: • Before you start development, the basic formatting should be decided • “This is how it will be, mostly, so you can go ahead and get started” is an invitation for Murphy and a recipe for wasted time and budget • For many of the requirements we will discuss, details can be resolved during the development process, but make sure to account for them in scheduling and budget
  15. 15. Common Requirements for PDF • • • • High fidelity (for print) and online version Turn on or off • TOC, Index, mini-TOC • Draft comments, crop marks, watermark, change markup… Variable sized documents and fold-outs • Letter, A4, custom sizes (fitting it in the box…), base on locale • Custom sizes meant for folding with exact spacing requirements Variable page size and orientation • Displaying a single topic / page / table / figure in landscape or different page size – e.g. fold-outs, large diagrams
  16. 16. Common Requirements for PDF • • Custom cover and back pages • Custom cover graphic • Title, alternate titles • Serial number, publication date, revision number, etc. • Copyright information • Contact information, addresses, • Generally driven using metadata, outputclasses Automated watermarks • Example: generate based on metadata combined with current date • Webinar: Suite Labs: Adding a Watermark to your PDF Output https://www.youtube.com/watch?v=tL6PFDVItEQ
  17. 17. Common Requirements for PDF • • • • Page breaks and keep-with-next • Tends to irritate people the most: folks are used to tweaking manually • Complexity: elements that span multiple pages • Can build logic in the style sheets approximating the thought process of a real person adding manual page breaks • Can support adding break instructions manually in the source DITA • Does not work properly in Apache FOP Table footnotes – appear after the table instead of bottom of page Flagging – based on conditionalization Change tracking • Via the authoring tool • Via the review tool • Comparison between 2 document revisions
  18. 18. Other PDF Requirements • • • • • Bar codes and QR codes – generate automatically using AH extension Section 508 compliance • Enable PDF to be read by a screen reader • AntennaHouse extension adds attributes to the PDF for elements such as links Show tags in the output for review Links between documents – instructor and participant guides MathML for equations • Render in PDF using AntennaHouse extension • Render into HTML by automatically generating graphics • Webinar: Implementing MathML with DITA XML https://www.youtube.com/watch?v=fnlZcIwJeMw
  19. 19. PDF Rendering Tool • • • Choose tool that will support all your requirements • Antenna House • RenderX • Apache FOP If need basic output: Apache FOP will be OK • Not supported well: Orphan/widow rules, page breaks Antenna House • Support for EPS (with GhostScript) • Other extensions available (MathML, barcodes, etc.) • Excellent localization support • Tools for Japanese index sort, regression testing
  20. 20. Considerations for Localization Support for localized outputs • Localization is generally supported with the DITA-OT • Multilingual documents not supported out-of-the-box but can be done • When done right: use one style sheet for all languages Customization • Font usage • Varies according to the character set • Automate right-to-left vs left-to-right (header, footer, cover, margins…) • Formatting • Use alternatives for emphasizing text in languages that do not use italics, bold or quotes as used in most other languages, for example:  「Japanese italicized text」  «Chinese italicized text »  “Chinese bolded text ” • Display Japanese dates in the format: 2013 年 8 月 13 日
  21. 21. Considerations for Localization • • • Variable strings • Text that is static throughout the content but vary per language Examples: “Warning” “Table of Contents” • DITA-OT already defines most commonly used strings • Often need to add new strings for copyright, address, special headings, etc. Index and glossary sort: Chinese and Japanese do not sort alphabetically – there are 2 options: • Use <index-sort-as> and <gloss-sort-as> to manually specify sort and group orders • Use AntennaHouse sort module which automates the sort Page size • Specify based on locale • Affects placement of headers/footers, margins, front/back covers
  22. 22. Considerations for Graphics and Media • • • • Support for high-res graphics and EPS • EPS supported by AntennaHouse + GhostScript Automated conversion during publishing from EPS to other formats (e.g. PNG) for use with HTML Whether to use SVG • XML format; often used for graphics with call-outs • Easier to localize – with some caveats… • Allows you to change the text inside the graphic during publish time • Can automatically convert to other formats (e.g. PNG) Embedded links to video
  23. 23. Considerations for Graphics and Media • • Sizing for HTML • Automatically generate smaller graphics OR rely on CSS • If use CSS, the sizing is controlled by the browser; sometimes less quality Display thumbnails • When clicked, display a large rendition as an overlay • Good for large figures or charts
  24. 24. General Requirements for HTML • • • • • • Formatting: fonts, sizes, spacing… Figure and Tables • Numbering: “for print” scheme is not the default for HTML Numbering generally makes sense per topic Generally we recommend to turn off numbering; only display the title • Titles: display above or below • Cells to span • First row color Flagging based on conditionalization Draft comments: format, view on-demand Embed Google analytics code “Mark of the web” – still an issue for older Windows and IE
  25. 25. General Considerations for HTML HTML5 • • • • • • Latest buzzword… Current browsers are not fully supporting HTML5; consider implementing fallback options where there are differences in support Decide which HTML5 features you would like, check they are supported in the required browsers, and TEST!!! Semantic elements: article, header, footer, section, aside, nav, figure, figurecaption, details Video • not supported by some browsers • still generally requires support for Javascript APIs for embedding controls • Consider the video encoding and how supported in browsers E.g. Chrome, Firefox, Opera all support WebM. Safari and IE only support h264 (recommended) Microdata attributes: @itemscope, @itemprop – used for search weighting
  26. 26. General Considerations for HTML Section 508 Compliance • • • • • Accessibility to people with disabilities Facilitates more effective reading for computerized screen-readers List of regulations: http://accessibility.psu.edu/section508 Examples • @alt for images need to be populated – generally, comes from the source XML content, some automatically populated using style sheets (e.g. logos, note icons) • Web pages shall be designed so that all information conveyed with color is also available without color. Supplement color coding with other signals such as shape or text HTML5 compliance with Section 508 • Section 508 has not been updated to correspond with HTML5 • Example: Section 508 requires a <summary> tag, which is deprecated in HTML5
  27. 27. Choosing an Online Help Platform Platforms available: • HTML Help (CHM) – not recommended: • Only works on Windows client, not cross-platform or server-enabled • Very little customization possible • No longer supported by Microsoft • Does not support modern CSS, which means you cannot share style sheets between help systems • SuiteHelp • oXygen • Webworks • Flare • Robohelp • Eclipse
  28. 28. Choosing an Online Help Platform: Considerations • • • • • Browser support • Big 4: IE, Firefox, Chrome, Safari • IE: difficult to support older version without many work-arounds Support for different operating systems: Windows, Mac, Linux Should not be based on frames • Deprecated in HTML5 • Causes security problems on many browsers • Slow • Not mobile friendly Context sensitivity Quality of search • Javascript-based vs. server-based • Server-based can provide true phrase search, morphology/fuzzy, etc. • Search highlighting, snippets
  29. 29. Customizations for Online Help • • • • • TOC images, how to highlight when selected Index: yes or no Glossary: yes or no • Alphabetization can be automated, but grouping is more difficult to implement Links: which to generate • Parent links • Child links • Next/previous • Related links, and whether to group them by topic-type Breadcrumbs
  30. 30. Customizations for Online Help • • • • • • Print • Current topic • Current topic and all child topics • All topics in help Email link to the current topic Link to a PDF version of the manual Re-sizable navigation pane Custom Footer Custom home page
  31. 31. General Requirements for ePUB • • • • • Formatting: much more limited than on other formats; many quirks Challenge: ePUB is generated using HTML, but is presented like a book Topic chunking: which topics should be rendered and flow together: often this is different than for HTML-based help Cover page Which ePUB readers to support? • Different readers on different mobile platforms differ widely in their support for CSS • Kindle is a different format: mobi Reality Check • You must test the output on each of the devices and readers that you want to support • There are common readers, such as Aldiko
  32. 32. General Requirements for Mobile • • • • Responsive vs adaptive design • Responsive: the help automatically refits itself using CSS media queries and grids to optimize the usability for different device sizes • Adaptive: the help is designed for a particular range of sizes Considerations: • Which device sizes? • Which OS? • HTML5-based vs native app TOC navigation • Generally only shows the top level • Navigate to lower levels through links on the topic pages jQuery Mobile reponsive UI system is commonly used • Supports different sizes well without concern for media queries and grids
  33. 33. General Requirements for Mobile • • • • Gestures • swipe, pinch, zoom/pan graphics Search • Since the help is commonly hosted on a web server, it is easier to implement a more powerful search engine such as SuiteHelp+ Embedding videos • Embedded links to YouTube Media • Not all media types supported out of the box • Some require special processing e.g. swf needs an HTML <object> element
  34. 34. Documenting the Style Sheets Now that we have all these customizations, how do authors use them? Document the style sheets • Outputclasses • Parameters • Metadata usage for the publication
  35. 35. Pushing the Envelope… Some advanced use cases 1. 2. 3. 4. List of Effective Pages Multilingual foldouts Modifying graphics during runtime using SVG Automated re-branding online help based on metadata using SuiteHelp
  36. 36. Case Study: Modifying graphics during runtime using SVG 1. Icon graphic for standards commission needs to have the serial number embedded depending on the geographical location of sale 2. During publishing, serial number is inserted into the SVG from metadata 3. The Catch: Icons need to flow on back cover from bottom right to left, then up… 4. Solution: Rotate the entire back page 180 degrees, so can flow from top left to bottom right…. the graphic file needs to start upside-down
  37. 37. Automated Re-Branding online help using SuiteHelp
  38. 38. Automated Re-Branding online help using SuiteHelp
  39. 39. Next Level: Dynamic Web • • • • • Variety of content: documentation, videos, how-to articles, safety information, data sheets, marketing material Context filtering: goal-oriented filtering to contextually relevant content Personalized docs: allow readers to assemble content on demand and render to PDF for print and ePub for offline mobile access Audience Participation: allow your audience to add new content, comment on existing content, express approval, and easily share knowledge with others Modern User Experience: smooth transition between mobile and desktop • Activity often starts on mobile, moves to desktop, returns to mobile • Internet connection not always available
  40. 40. Keep in Touch! Let us know how we can help you. For additional information, contact: Yehudit Lindblom Joe Gelb solutions@suite-sol.com U.S. Office (609) 360-0650 EMEA Office +972-2-993-8054 www.suite-sol.com Follow us on Linked-In http://www.linkedin.com/company/527916