Presented by Erika Frensley COMMON SENSE DITA Presented by Erika Frensley
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
In this presentation Explanation of DITA How DITA works Description of common and basic DITA parts DITA Resources
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
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
Unstructured Authoring Single use, finished product Structured Authoring Advanced implementation using standard and reusable components from DITA
DITA 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
My basic DITA implementation topic based, structured authoring with basic reuse
DITA Concepts Elements Attributes Maps/DITAMaps References/Links Reuse Transform/Publishing
DITA is a coding markup language, similar to HTML. CODING ALERT DITA is a coding markup language, similar to HTML. For the best understanding of DITA, become familiar with markup conventions and syntax.
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.
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>
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
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.
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.
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.
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
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.
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>.
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>.
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.
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.
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.
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.
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>
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">
Reuse Reusing topics in multiple DITAmaps Pull reuseable elements into topics Push reuseable elements into topics
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.
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!
Conref Example Result Source file: Target 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.
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!
Conref push example Source file: Target file: Result <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…
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.
Resources DITA OASIS Standard www.dita-archive.xml.org DITA for the Impatient www.xmlmind.com/tutorials/DITA Oxygen XML documentation – DITA authoring https://www.oxygenxml.com/doc/versions/20.1/ug- author/topics/author-dita.html DITA Open Toolkit https://www.dita-ot.org/ Techwhirl – What is DITA? https://techwhirl.com/what-is-dita/ DITA Writer http://www.ditawriter.com/