1 / 34

COMMON SENSE DITA

Learn about DITA and how it works, including common and basic DITA parts, authoring types, and advanced implementation. Understand DITA concepts such as elements, attributes, maps, references, and publishing.

mmaxey
Download Presentation

COMMON SENSE DITA

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. COMMON SENSE DITA Presented by Erika Frensley

  2. About Me • Over 25 years as a technical writer in the financial, oil&gas, medical, and software industries • Created online and paper documentation • FrameMaker, Robohelp/Madcap Flare, Word, HTML, graphics, and now DITA • Part of STC Houston for over 20 years in various capacities, including webmaster, competitions manager, and now President

  3. In this presentation • Explanation of DITA • How DITA works • Description of common and basic DITA parts • DITA Resources

  4. Authoring Types Unstructured Authoring • Static content that is locked in one format for a single purpose • Reuse is limited to manual copy and paste. Structured Authoring/Topic Based • Content is chunked into smaller, self-contained pieces of content • Chunks can be organized or reused in multiple topics DITA • Structured Authoring/Topic based that separates formatting from content, allowing multiple formats from the same content

  5. What is DITA • Darwin Information Typing Architecture • Open Source Standard for information typing and methodology • XML defines elements of information so that they can be used and manipulated in different ways according to software needs • DITA is XML customized for information and documentation

  6. Unstructured Authoring Single use, finished product Structured Authoring Advanced implementation using standard and reusable components from DITA

  7. DITA Advanced Implementation Advanced implementation • Analyzes the current information and determines an information typing structure and methodology • Creates templates and models for writers • Determines common content and standard naming conventions for content • Determines output types and settings

  8. My basic DITA implementationtopic based, structured authoring with basic reuse

  9. DITA Concepts • Elements • Attributes • Maps/DITAMaps • References/Links • Reuse • Transform/Publishing

  10. CODING ALERT DITA is a coding markup language, similar to HTML. For the best understanding of DITA, become familiar with markup conventions and syntax.

  11. Elements • Building blocks of information in DITA • Text that is tagged to indicate what kind of information it is • Topics – the top element in DITA • Metadata • Title • Steps and Commands (cmd) • Lists (OL/UL) • Img • Table • Elements can and usually do contain other elements • Elements must be identified to be found and referenced in the DITA project.

  12. Element Examples <topic id="docbook_or_dita"> <title>DITA or DocBook?</title> <shortdesc>Both DITA and DocBook are both mature, feature rich, document types, so which one to choose?</shortdesc> <body> <p>DocBook 5 is a mature document type, featuring decent XSL stylesheets allowing conversion to a variety of formats, based on thebest schema technologies: RELAX NG and Schematron.</p> <section id=“section_name”> <title>Section Title</title> DITA concepts (topics, maps, specialization, etc) have an immediate appeal to the technical writer. Choose DITA if its technical vocabulary is sufficiently expressive for your needs or if, anyway, you intend to specialize DITA. </section> </body>

  13. Attributes • Characteristics/properties of an element • Contains two parts • A name • A value contained in quotes • Most important global attribute: <elementtype id=“idname”> • Attributes depend on the element type

  14. ID Attribute • ID identifies an element such as topic, a section, table, image, steps to make it referenceable • ID must be unique in a topic. • References (links) will refer to the dita topic file and the ID in that file: <p>Make sure you have performed the <xref href="topic_structure.dita#preconfig"/>pre-configuration steps.</xref> </p> The link will go to the dita file topic_structure.dita, to the block of text with the ID preconfig.

  15. Maps/DITAMaps • References to topics in a specified order and hierarchy, and is most often used to create a deliverable or library of content. • Similar to Table of Contents in Flare/Robohelp • DITAMaps can contain smaller map files (modular) • DITAMaps and references inside DITAMaps can have attributes that will affect filtering, sorting, or display of data.

  16. References/Links • Links to the other DITA documents, or to a website or document that is not part of the DITA project • References can be: • Topicref used in DITAMaps • Xref link to other DITA documents • Conref – used to reference content that can be reused and inserted into topics.

  17. Transform/Publishing • Scripts use the DITAMap to determine the content and order of the output, and then processes the DITA files to a specific output such as Word, PDF, HTML Help, Webhelp or DocBooks • Transformation includes XSLT (Extensible Stylesheet Language Transformations) and uses style sheets for the deliverable type (css, dotx) Parameters can be specified to set: • The format for table and figure captions • The footer and header • Whether related links are automatically created and applied

  18. Topic Types • Topic - general, base topic type from which all other topic types are specialized • Task - For procedural information such as how to use a dialog box. • Concept - For general, conceptual information such as a description of a product or feature. • Reference - For reference information. Each topic type includes elements unique to the topic type.

  19. Topic Elements Simple and basic element that can be used when a more specific topic type is not appropriate. • Contains <title> and <body> element, with optional <shortdesc> or <abstract> elements before the <body> element. • <body> can contain almost any nonspecific element such as <section>, <table>, <image> <section>, <example> as well as paragraphs, lists, and other elements. • <related-links> element can be included at the end of the <body>.

  20. Task Elements Describes how to perform a task using sequential steps • Contains <title> and <taskbody> and optional <titlealts>, <shortdesc>, <prolog>, and <related-links>. • <taskbody> contains the following elements in this order: <prereq>, <context>, <steps>, <result>, <example> and <postreq>.

  21. Task Elements (cont) <taskbody> Elements • <prereq> - Information needed before starting the current task. • <context> - Background information for the task. • <steps> - contains one or more <step> elements. Each <step> contains a <cmd> element. Optional elements: <info>, <substeps>, <tutorialinfo>, <stepxmp>, <choices> or a <stepresult>, although these are optional. • <result>Describes the expected outcome for the task. • <example>Provides an example that illustrates the task. • <postreq>Describes the next steps after the successful completion of the current task.

  22. Concept Elements Describes the reason or explanation and provides background to help readers understand essential information about a product, interface, or task. • Contains <title> and a <conbody> and optional <titlealts>, <shortdesc>, <prolog>, and <related-links>. • <conbody> element can contain <section>, <example> as well as paragraphs, lists, and other elements. • Note: Sections or examples in <conbody> can be followed only by other sections or examples.

  23. Reference Elements Describes the regular features of a subject or product • Contains <title> and a <refbody> and optional <titlealts>, <shortdesc>, <prolog>, and <related-links>. • <refbody> element can contain <section>, <refsyn> (contains syntax or signature content (for example, a command-line utility's calling syntax, or an API's signature), <table> (can be a <simpletable> or <properties> table.

  24. DITAmaps • Organizes DITA topics into hierarchical groups and structures. • Contains <map> with <title>. <topicref> defines the linking structure. <topicref> can be nested. Example: <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"> <map> <title>Examples for advanced reuse</title> <topicref href="c_filtering_and_flagging.dita"/> <topicref href="c_conrefpush_target.dita"/> <topicref href="c_conrefpush_sources.dita" processing-role="resource-only"/> </map> • Note: Since a ditamap defines the relationship between topics, related links (when built) are determined only by the ditamap.

  25. DITAMap Example <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"> <map> <title>Examples for advanced reuse</title> <topicref href="c_filtering_and_flagging.dita"/> <topicref href="c_conrefpush_target.dita"> <topicref href=“c_samplefile1.dita”/> <topicref href=“c_samplefile2.dita”/> </topicref> <topicref href="c_conrefpush_sources.dita" processing-role="resource-only"/> </map>

  26. Links (Xref) Elements • Links or otherwise cross-references text within a topic to other topics, elements within a topic, or resources external to the DITA collection. Examples • Reference to a topic (or the first topic in a composite (ditabase) topic):  <xref href="topic1.dita"> • Reference to an element inside a DITA topic: <xref href=" topic1.dita/#topicSummary/elementid"> • Reference to an external resource: <xref href="http://www.example.org">

  27. Reuse • Reusing topics in multiple DITAmaps • Pull reuseable elements into topics • Push reuseable elements into topics

  28. Reuse topics in DITAmaps • The same topic can be referenced in different DITAmaps. • Since the DITAmap controls the hierarchy, the same topic can be at the top level of a topicref or nested inside a topicref. • The same topic can even be used multiple times in the same DITAmap.

  29. Pull reuseable elements into topics <conref> allows the specified content in the source file to be included at the specified point in the target file. • The source for the repeated content, such as a note, is kept in one file. • The target file uses the <conref> element to pull the repeated content into the target topic. This is not copy and paste!

  30. Conref Example Source file: <topic id="topic_123"> <…> <note type="note" id="bolt_warning">Don't overtighten the bolts, as it may cause stripping.</note> Target file: <steps> <step><cmd>Use the wrench to tighten the bolts.</cmd> <note conref="notes.dita#topic_123/bolt_warning"/><step> Result 1. Use the wrench to tighten the bolts.Note: Don’t overtighten the bolts, as it may cause stripping.

  31. Push reusable elements into topics <conref> and <conaction> allows the specified content in the source file to be included at the specified point in the target file. • The source for the repeated content, such as a note, is kept in one file. • The source file uses the <conref> element with the <conaction> attribute to push the content into the target topic at the specified spot in the topic. The target topic is not modified!

  32. Conref push example Source file: <topic id="topic_123"> <…> <p conaction="mark" conref="c_servicing.dita#service/regular_servicing" /> <p conaction="pushafter"> Your local dealer is Snell Performance Vehicles. </p> Target file: <p id="regular_servicing">You should have your car serviced regularly.</p> <p>The service intervals...</p> Result You should have your car serviced regularly. Your local dealer is Snell Performance Vehicles. The service intervals…

  33. Writing for Reuse Any taggable element can be reused in another topic. • Minimize content and avoid context such as “in the following steps”. • Chunk information into discrete parts that can be reused elsewhere. • Use standard phrasing and language in all topics.

  34. Resources • DITA OASIS Standardwww.dita-archive.xml.org • DITA for the Impatientwww.xmlmind.com/tutorials/DITA • Oxygen XML documentation – DITA authoringhttps://www.oxygenxml.com/doc/versions/20.1/ug-author/topics/author-dita.html • DITA Open Toolkithttps://www.dita-ot.org/ • Techwhirl – What is DITA?https://techwhirl.com/what-is-dita/ • DITA Writerhttp://www.ditawriter.com/

More Related