Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

DITA Quick Start for Authors Part II


Published on

Published in: Technology, Education

DITA Quick Start for Authors Part II

  1. 1. DITA Quick Start Workshop for Authors: Part 2 Joe Gelb August 27, 2013
  2. 2. Who is this guy? 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 • Blue Chip Customer Base • Hundreds of Person Years of Experience on Staff
  3. 3. Introduction to DITA: Main Topics Part I  Introduction to XML  Overview of DITA Part II • Topics: The Basic Information Types • Maps: Assembling Topics into Deliverables • Linking Methods
  4. 4. Topics: Basic Information Types • Each topic answers a single question • Three basic information types, specialized from the standard topic: • Concept Background, descriptive, conceptual information that explains what something is or how it works Answers: “What is this?” • Task Step-by-step instructions for reaching a certain goal; Answers: “How do I do this? • Reference Tables, lists, diagrams, process flows and other information that must be easy to look up
  5. 5. Topics: Basic Information Types • Additional topic types: • Glossary Entry glossentry • Learning Topics Plan, Overview, Content, Summary, Assessment Other Specializations Machine Industry Task, API, JavaAPI, Troubleshooting, and more Available as plug-ins from SourceForge
  6. 6. DITA Base Topic Forms the basic topic structure, from which the other information types are specialized
  7. 7. Basic Topic Elements title Label for the topic; element also used to label sections, examples, figures, tables, etc. shortdesc Short description: purpose or theme of the topic; highly recommended that all topics have one abstract Allows a wider range of content than shortdesc (new for DITA 1.1) prolog Contains information about the topic entered by the author or by machine body Container for the main body of the topic section Subset of information directly related to the topic; does not represent hierarchy and cannot be nested example Section with examples that illustrate or support the topic related-links Links to related information
  8. 8. DITA Concept Background, descriptive, conceptual information that explains what something is or how it works
  9. 9. DITA Task Step-by-step instructions for reaching a certain goal
  10. 10. DITA Task
  11. 11. DITA Task Main taskbody elements prereq Pre-requisite; things the user needs to know or do before starting the current task context Background information; helps the user understand the purpose of the task and what they will gain by completing the task; should be brief section General organizational container for content which can include a title [1.2]
  12. 12. DITA Task Main taskbody elements step Action that the user must follow to accomplish a task; must contain a command <cmd> element which describes the particular action result Describes the expected outcome for the task example Examples that illustrate or support the task postreq Steps that the user should do after the successful completion of the task [1.2]
  13. 13. DITA Task Main step elements note Calls attention to a particular point hazard statement Hazard warning information, based on ANSI and ISO standards cmd Provides the active voice instruction for completing the step; should not be more than one sentence. info Provides additional information about the step substeps Allows you to break a step into separate actions; avoid wherever possible
  14. 14. DITA Task Main step elements tutorialinfo Additional information that is useful when the task is part of a tutorial stepxmp Used to illustrate the step choicetable Contains a series of optional choices available within the step choices Used when the user will need to choose one of several actions while performing the step stepresult Provides information on the expected outcome of the step
  15. 15. DITA Reference Tables, lists, diagrams, process flows and other information that must be easy to look up
  16. 16. DITA Reference
  17. 17. DITA Reference Main refbody elements section Used to organize subsets of information that are directly related to the topic; does not represent hierarchy refsyn Contains syntax, signature content, or a brief, possibly diagrammatic description of the subject's interface or high- level structure example Examples that illustrate or support the reference topic table, simpletable Tabular information properties Gives a list of properties for the subject; can include the type, value, and a description refbodydiv Container for grouping content; can be used for specialization and reuse [1.2]
  18. 18. Topic Elements: Short Description: shortdesc • Generally output as the first paragraph in the topic • Should be simple enough to be suitable for use as a link preview or summary • If first paragraph cannot be simple enough, use the <abstract> element with <shortdesc> inside • Highly recommended that all topics have one: if there is only one paragraph in the topic, it is preferable to include a shortdesc and leave rest empty • Should be a single, concise paragraph with one or two sentences
  19. 19. Topic Elements: Short Description: Recommended Content Task Explain what the task helps users accomplish, benefits, when the task is appropriate or why it is necessary Use complete sentences, not fragments Concept Provide concise answer to “What is this?” or “Why do I care about this?” Should contain the main point of the concept Use complete sentences, not fragments Reference Describe what the reference item does, what it is, what it is used for If you use fragments, use consistent phrasing across your content set
  20. 20. Topic Elements: Prolog • Contains information about the topic as a whole • author information • subject category • Entered by the author or machine- maintained • Generally is not displayed in the published output • May be used by processes that generate search indexes or customize navigation
  21. 21. Topic Elements: Prolog -> Metadata • Provides information about the content and subject of a topic • Index terms can be coded in the <keywords> element
  22. 22. Body Elements Support the most common types of content for topics ph phrase; used to organize content for reuse or conditionalize keyword identifies a keyword xref cross-reference dl definition list desc description pre, lines preformatted text cite citation q, lq quotation, long quotation sectiondiv Untitled containers [1.2] table, simpletable p paragraph ol, ul ordered, un-ordered list li list item in a <ul> or <ol> sl simple list sli list item in a <sl> note calls attention to a particular point fig figure with an optional title image artwork; can be inline or on next line hazardstatement [1.2]
  23. 23. Domain Elements Defined vocabularies for common use across different topic types Programming apiname, codeblock, paraml, syntaxdiagram … Software msgblock, cmdname, varname, filepath, userinput User Interface uicontrol, menucascade, shortcut, wintitle, screen Utilities imagemap, area, shape, coords Indexing index-see, index-see-also, index-sort-as Typographic b, u, i, tt (teletype), sup, sub xNAL Elements for name and address [1.2]
  24. 24. Common Attributes id anchor; target for references conref component reference to an element within another topic importance priority: obsolete | deprecated | high | low … rev revision level of the element status status of the element: new | changed | deleted … outputclass role that the element is playing; used for output formatting Conditional attributes: support conditional processing audience intended audience for the element product name of the product which the element applies platform indicates operating system or hardware otherprops can be used for any other properties props root attribute meant to be specialized
  25. 25. Introduction to DITA: Main Topics  Introduction to XML  Overview of DITA  Topics: The Basic Information Types • Maps: Assembling Topics into Deliverables • Linking Methods
  26. 26. DITA Maps: Assembling Topics into Deliverables • Assemble any number of topics into sequences for print or online delivery • Organize topics into a hierarchy • Heading levels based on context and position, not the topics themselves • Use sub-maps within maps • Allows you to create building blocks • Maps can be filtered using conditional processing: master map re-use
  27. 27. • Can create different types of maps: • Solution-oriented How products and procedures work together • Task-oriented How to accomplish a specific goal • Feature-oriented What does a product or component do • Map specializations • Bookmap • Learning DITA Maps: Assembling Topics into Deliverables
  28. 28. DITA Map Organizes topics into sequential hierarchy and relationship tables
  29. 29. DITA Map Main elements topicref Identifies a DITA topic or other resource; may contain other <topicref> elements, allowing you to express hierarchies and relationships topicmeta Defines the metadata that applies to a topic when it appears in a map and to the other topics contained by the same element that contains the <topicmeta> element topichead Provides a title-only entry in a navigation map topicgroup Creates groups of <topicref> elements without affecting the hierarchy; typically used to identify groups for linking and metadata without affecting the resulting toc/navigation output reltable Relationship table; defines relationships between topics
  30. 30. Bookmap Creates deliverables that are structured like traditional print publications
  31. 31. Bookmap Front and back matter
  32. 32. Introduction to DITA: Main Topics  Introduction to XML  Overview of DITA  Topics: The Basic Information Types  Maps: Assembling Topics into Deliverables • Linking Methods
  33. 33. Linking Methods • Hierarchy links • Cross-references: internal and external • Related Links • Component references: conref • Indirect addressing: keys [DITA 1.2]
  34. 34. Hierarchy Links • Based on hierarchy links in the map: nested topicrefs • Links to parent, children • Generated automatically by the DITA Open Toolkit during publishing • Child links: includes title and short description
  35. 35. Cross-reference: <xref> • Internal and external • Best practice: reduce or eliminate usage of external cross- references • External link: <xref href=“path/filename.dita#topicID/elementID” • Internal link: <xref href=“#elementID”
  36. 36. Related Link: <link> • Related Links • Listed in Topics in <related-links> <link href=“path/filename.dita#topicID/elementID” type=“task” format=“dita” scope=“local”> <linktext>title override</linktext> </link>
  37. 37. Relationship Tables • Defines relationships between topics based on the table model of rows, columns and cells • Table cells can contain <topicref> elements, which are then related to other <topicref> elements in the same row • By default, is not output for navigation or TOC purposes; used only to define relationships that can be expressed as topic-to-topic links • Can be used with hierarchies and groups to manage all related links in an information set
  38. 38. Relationship Tables • Each row represents a separate set of relationships and links • No relationship exists between the rows in a table • Topic references are not needed in every cell within a row • Each cell can contain multiple topic references • Topic references can be repeated in multiple rows
  39. 39. Content Reference: conref • Replaces content of element with the content of another element • Implemented as an attribute • Component markup must be valid inside the element making the reference <note conref=“path/filename.dita#topicID/elementID”>
  40. 40. Conref Range [DITA 1.2] • Allows you to include a range of elements instead of a single element • Use the conref attribute to reference the first element in the range, and the new conrefend attribute to reference the last in the range
  41. 41. Conref Push [DITA 1.2] • Reverses the direction of reuse from a pull to a push • Use the new conaction attribute to determine whether content is rendered before, after, or in place of the element being referenced • Useful for pushing content into preset content templates <step conaction="pushreplace" conref=“changingtheoil.dita#changeoil/removeoilfilter"> <cmd>Use the special wrench for tractors</cmd> </step>
  42. 42. Indirect Key-based Addressing [DITA 1.2] • Layer of abstraction: resources addressed by references can be defined at the DITA map level • Allows relationships to resolve to different resources based on different contexts: product-based, customer-based, subscription-based, etc. • Links refer to key names, the keys are bound to resources via the map • Different maps can bind the keys to different resources • Keys defined using topicref or keydef elements • Topics can be given symbolic names using the keys attribute
  43. 43. Defining Keys Using keydef • Topic will not be included in the map navigation • Used for variable text <keydef keys="oilterm" href=“oiltype.dita“ processing- role="normal"/> Using topicref • Topic will also be included in the map navigation <topicref keys="oilchange" href=“changingoil.dita" />
  44. 44. Linking from Terms and Keywords • Can associate glossary and index term definitions in a map • Entries may be referenced from other topics <map> <keydef keys=“gauge” href=“oil-gauge.dita”> </map> … <p>Use the <term keyref=“guage”>oil gauge</term> to measure the amount of oil currently in the engine.</p>
  45. 45. Substituting Variable Content • Variable text can be defined as keywords in the map • Variable text can be used in different topics <map> <keydef keys=“oiltype”> <topicmeta> <keywords><keyword>10W-30</keyword></keywords> </topicmeta> </keydef> </map> … <p>Only use <keyword keyref=“oiltype” /> in your vehicle.</p>
  46. 46. Producing Custom Documents • Substitute for conditional processing • Use conkeyref in topics to pull in pre-defined content • Use a different map for each document variation to bind keys to the proper pre-defined content <p conkeyref=“oiltype”></p> map <map> <!-- this map is for cars --> <keydef keys=“oiltype” href=“car-engine-oils.dita”> </map> car-engine-oils.dita <p>Use only 10W-30 or 10W-40 in your car, depending on …</p>
  47. 47. Introduction to DITA: Main Topics  Introduction to XML  Overview of DITA  Topics: The Basic Information Types  Maps: Assembling Topics into Deliverables  Linking Methods
  48. 48. DITA Quick Start End of Part II Join us for our upcoming webinars: • Getting Started with the DITA Open Toolkit • Getting Started with Information Architecture • System Architecture of a Basic DITA Toolset • Migrating to DITA: Building a Project Plan • Migrating to DITA: Defining Your Style Sheet Requirements • Migrating to DITA: Defining Your Conversion Requirements • Migrating to DITA: Defining Your Translation Requirements To learn how the DITA Quick Start Program can get you up and running:
  49. 49. Be in touch For additional information, contact: Joe Gelb U.S. Office EMEA Office (609) 360-0650 +972-2-993-8054 Follow us on LinkedIn