Cheaper, Faster, Better DITA Implementations, Part 2


Published on

In continuation of our first webinar, Part 2 of the Cheaper, Faster, Better DITA series will walk through a simplified example of how to construct a DITA architecture for a documentation set. The example will demonstrate how the right approach will simplify DITA authoring, managing, and publishing content.

Published in: Business
1 Comment
  • On slide 25 (Attribute Specializations) I don't understand why @translate would ever be specialized.

    The idea behind this attribute makes sense to me with its defined usage in DITA. The assumption being that translation is usually based on one 'mother' language (with most documents being written in English, or French, etc) and all other translations being based off of the mother language version. This means that one will usually assume that everything in a document is to be translated, with the exception of anything marked @translate='no' (ie: perhaps product names, etc). So, why add additional values to this attribute? There are two things I can guess you might be getting at (and both seem wrong to me):

    1) You wish to specify which language to translate to? This is not something one would normally specify in a sub portion of a document. Are documents not always translated as a whole? In that case the decision of which language to translate the document to is part of an external process.

    2) You wish to specify which language to translate from? The attribute xml:lang already exists for specifically identifying the language of portions of documents so there is no need to define another attribute that does the same thing is there?
    Are you sure you want to  Yes  No
    Your message goes here
  • Be the first to like this

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

No notes for slide

Cheaper, Faster, Better DITA Implementations, Part 2

  1. 1. Prepared by © 2009 Lasselle-Ramsay Presented by Secrets to Cheaper, Faster and Better DITA Implementations Part 2 Presenter from Lasselle-Ramsay Tom Voltz
  2. 2. Welcome! • Today’s event is being recorded – link available in follow- up email • Use Q&A panel to submit questions for Q&A session • Full screen view available for slides
  3. 3. Our Presenters Joan Lasselle President Tom Voltz Technology Consultant
  4. 4. Lasselle-Ramsay Industry Expertise 27 years supporting Fortune 100 clients with their content infrastructure
  5. 5. Overview for Today • Part I Review • Sample Documentation Set • Specialization Best Practices
  6. 6. Poll – Part I Question: Were you able to watch the first part of this webinar?  Yes  No
  7. 7. Part I Review DITA – Out of the Box DITA – Specialized
  8. 8. • Fundamental DITA Open Toolkit architectural feature: Myth Busting
  9. 9. Effort Mary Joe Units of Labor Content Analysis Training Development Training Delivery Specialization
  10. 10. Sample Documentation Set • 7 Product Variations • User Manual • Context Sensitive Online Help
  11. 11. Lasselle-Ramsay Six-Point Approach
  12. 12. Define User Experience • Develop Personas – Representative customers • Task Analysis – Lifecycle of product from customer perspective – Specific tasks, connected to personas
  13. 13. Finding: Distinct Audiences • Jake – End User – Manual to big, not useful – Context sensitive help too brief, frustrating • Sam – Field Service Technician – Insufficient detail – Can’t lookup error codes quickly – Procedures are confusing (inconsistent with user interface)
  14. 14. Analyze Workflow • Map of current content lifecycle • Alignment of other related processes • Opportunity assessment
  15. 15. Finding: Process Misalignment Product Development Agile Process Content Development Traditional Release 3.0
  16. 16. Finding: Process Misalignment Product Development Agile Process Content Development Aligned
  17. 17. Feature as ‘Content Envelope’ User Guide Field Manual Marketing
  18. 18. Content Analysis Findings • Content audit • Redundancy and overlap • Gaps • Content to retire
  19. 19. Summary of Findings
  20. 20. Specialization Elements
  21. 21. Specialization Elements Attributes
  22. 22. Structural Elements – Maps Name Based On Contains Blocks Owned by UserGuide Bookmap Introduction Chapters Support Guide Index Tech Docs ReferenceManual Bookmap Description HowTos Error Codes Tech Docs Feature DITA Map Description HowTos Error Codes Configuration Notes Marketing Tech Docs QA
  23. 23. Block Elements – Topics and Concepts Name Based On Contains Notes Description DITA Topic Keywords ShortDescription MediumDescription LongDescription ShortDescription Topic – Section Paragraph Used in marketing materials, User Guide, Field Manual MediumDescription Topic – Section Paragraphs Used in marketing materials LongDescription Topic – Section Sections Paragraphs Used in UserGuide
  24. 24. Inline Elements – Domains Name Based On Notes UI DITA UI domain Available: Paragraphs Table Cells BrandElement Company specific domain Available: Anywhere Product names, etc. Programming DITA programming Available: Anywhere Only using 6 of the standard 25 elements, added 3 custom elements
  25. 25. Attribute Specializations Name Based On Notes @audience @audience Limit to following options: User Technician Internal-Only QA-Team @translate @translate Limit to valid language codes (‘en,’ ‘fr,’ ‘de,’ etc.) @legal_status @otherprops Required for specific block elements (e.g. copyright notice). Values (‘modified,’ ‘approved’)
  26. 26. Steps for Prototyping Specialization 1 Mock up representative content using generic DITA 2 Carefully review the existing domains and specializations 3 Remove as much as you can 4 Build the DTD 5 Revise mock up content with specializations 6 Iterate with SMEs
  27. 27. Specialization Best Practices Know the public DITA specializations Know the current DITA domains Preserve DITA Open Toolkit architecture
  28. 28. Specialization Best Practices Make sure DTD is easy to update Support ‘default’ and ‘flexible’ formats containers Create a DTD maintenance process
  29. 29. Questions and Next Steps 1-866-793-1542