Presentation is loading. Please wait.

Presentation is loading. Please wait.

Presented by Erika Frensley

Published byれんか いのら Modified over 5 years ago

Similar presentations

Presentation on theme: "Presented by Erika Frensley"— Presentation transcript:

1 Presented by Erika Frensley
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
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 implementation topic based, structured authoring with basic reuse

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

10 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.

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="

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 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.

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: 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…

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 Standard www.dita-archive.xml.org
DITA for the Impatient Oxygen XML documentation – DITA authoring author/topics/author-dita.html DITA Open Toolkit Techwhirl – What is DITA? DITA Writer

Download ppt "Presented by Erika Frensley"

Similar presentations

XML-XSL Introduction SHIJU RAJAN SHIJU RAJAN Outline Brief Overview Brief Overview What is XML? What is XML? Well Formed XML Well Formed XML Tag Name.

XML-XSL Introduction SHIJU RAJAN SHIJU RAJAN Outline Brief Overview Brief Overview What is XML? What is XML? Well Formed XML Well Formed XML Tag Name.
XML III. Learning Objectives Formatting XML Documents: Overview Using Cascading Style Sheets to format XML documents Using XSL to format XML documents.

XML III. Learning Objectives Formatting XML Documents: Overview Using Cascading Style Sheets to format XML documents Using XSL to format XML documents.
Table, List, Blocks, Inline Style

Table, List, Blocks, Inline Style
DOCUMENT TYPES. Digital Documents Converting documents to an electronic format will preserve those documents, but how would such a process be organized?

DOCUMENT TYPES. Digital Documents Converting documents to an electronic format will preserve those documents, but how would such a process be organized?
Cascading Style Sheets (CSS). Cascading Style Sheets With the explosive growth of the World Wide Web, designers and programmers quickly explored and reached.

Cascading Style Sheets (CSS). Cascading Style Sheets With the explosive growth of the World Wide Web, designers and programmers quickly explored and reached.
HTML Overview - Cascading Style Sheets (CSS). Before We Begin Make a copy of one of your HTML file you have previously created Make a copy of one of your.

HTML Overview - Cascading Style Sheets (CSS). Before We Begin Make a copy of one of your HTML file you have previously created Make a copy of one of your.
SPECIAL TOPIC XML. Introducing XML XML (eXtensible Markup Language) ◦A language used to create structured documents XML vs HTML ◦XML is designed to transport.

SPECIAL TOPIC XML. Introducing XML XML (eXtensible Markup Language) ◦A language used to create structured documents XML vs HTML ◦XML is designed to transport.
DITA Everyday by Tom Rathkamp

DITA Everyday by Tom Rathkamp
3 November 2008CIS 340 # 1 Topics To define XML as a technology To place XML in the context of system architectures.

3 November 2008CIS 340 # 1 Topics To define XML as a technology To place XML in the context of system architectures.
1 Chapter 11 Developing Custom Help. 11 Chapter Objectives Use HTML to create customized Help topics for an application Use the HTML Help Workshop to.

1 Chapter 11 Developing Custom Help. 11 Chapter Objectives Use HTML to create customized Help topics for an application Use the HTML Help Workshop to.
Tutorial 3: Adding and Formatting Text. 2 Objectives Session 3.1 Type text into a page Copy text from a document and paste it into a page Check for spelling.

Tutorial 3: Adding and Formatting Text. 2 Objectives Session 3.1 Type text into a page Copy text from a document and paste it into a page Check for spelling.
XP New Perspectives on Microsoft Access 2002 Tutorial 71 Microsoft Access 2002 Tutorial 7 – Integrating Access With the Web and With Other Programs.

XP New Perspectives on Microsoft Access 2002 Tutorial 71 Microsoft Access 2002 Tutorial 7 – Integrating Access With the Web and With Other Programs.
Understanding HTML Style Sheets. What is a style?  A style is a rule that defines the appearance and position of text and graphics. It may define the.

Understanding HTML Style Sheets. What is a style?  A style is a rule that defines the appearance and position of text and graphics. It may define the.
XML, DITA and Content Repurposing By France Baril.

XML, DITA and Content Repurposing By France Baril.
Creating a Simple Page: HTML Overview

Creating a Simple Page: HTML Overview
© 2007 IBM Corporation DITA code reviews Presenters: Megan Bock, Shannon Rouiller, Jenifer Schlotfeldt.

© 2007 IBM Corporation DITA code reviews Presenters: Megan Bock, Shannon Rouiller, Jenifer Schlotfeldt.
15 November 2005Linking Outside the Box1 Cross referencing between XML documents Bob Stayton Sagehill Enterprises

15 November 2005Linking Outside the Box1 Cross referencing between XML documents Bob Stayton Sagehill Enterprises
Lesson 4: Using HTML5 Markup.  The distinguishing characteristics of HTML5 syntax  The new HTML5 sectioning elements  Adding support for HTML5 elements.

Lesson 4: Using HTML5 Markup.  The distinguishing characteristics of HTML5 syntax  The new HTML5 sectioning elements  Adding support for HTML5 elements.
XML and XSL Institutional Web Management 2001: Organising Chaos.

XML and XSL Institutional Web Management 2001: Organising Chaos.
XP 1 CREATING AN XML DOCUMENT. XP 2 INTRODUCING XML XML stands for Extensible Markup Language. A markup language specifies the structure and content of.

XP 1 CREATING AN XML DOCUMENT. XP 2 INTRODUCING XML XML stands for Extensible Markup Language. A markup language specifies the structure and content of.

Similar presentations

Ads by Google