Introduction to DITA

1

Introduction to DITA

Bernard Aschwandenwww.publishingsmarter.com

www.publishingsmarter.com2 2:55

Bernard Aschwanden

President of Publishing Smarter

Worked in docs and training since 1992

Consultant and trainer in CMS, XML, DITA, and publishing technologies

STC Toronto Community Past President


Publishing Smarter

Works with clients to improve content creation, management, and distribution workflows

Provides content analysis, legacy file conversion, training, and support

Main goals are to reduce production costs, improve document quality, and increase employee productivity

Learner outcome

Understand core DITA

Present your team clear information about DITA and the pro's and con's it offers

See DITA applied to real world doc examples

Deliver the right content, to the right audience, at the right time, and in the right format



My disclaimer

I will be making blanket statements about DITA to keep things simple

Not all that I tell you will be 100% DITA, but

Slides are a reference, they go by quickly

Bonus materials may also be covered

About DITA

Summing up a complex idea in as few slides as possible

2

DITA should matter to you

A growing standard with vendor supportAdobe, JustSystems, Oxygen, Quark, third-party Word support, and much more

More companies looking for DITA skills

Not just structured writing; best practices:Planning content

Organizing information

Developing relationships

Using automation where it makes sense


Setting the stage

Most of the people in attendance have likely heard of DITA

There is a very short overview of DITA to put everyone into a similar mindset to start

Summation and open QnA session

Bonus materials as time allows



DITA in a single slide

D is for Darwin

IT is for Information Typing

A is for Architecture

DITA is primarily about Topic, Maps, Specializations

Some included specializations include

concept, reference, task, glossary (topic based)

bookmap (map based)

various domains (software, programming)

Core ideas within DITA


Maps

Used to plan, organize, and publish

Reltables

Build relationships between info in maps

Topics

Types of info in a map, generally as task, concept, or reference

Specializations

Customize as needed if other options are exhausted

Behind the scenes


Maps


Reltables


Topics


Specializations


AttributesWriting DITA

Key ideas that writers should focus on when starting

3

Starting points for writers

topic: A meaningful, stand alone unit of information, minimalist, well writtentask: Procedural details (step-by-step instructions)concept: Background info users need to knowreference: Quick access to factsattributes: Metadata used to further define elements

www.publishingsmarter.com 9:06 www.publishingsmarter.com14

Commonly used elements

paragraph elementstgroup and table elementsbody related elements

bodyconbodyrefbodytaskbody

section and example elementsxref elementlist elements

ulolli

figure and image elements

task related elementsprereqcontextstepsresultexamplepostreq

steps related elementssteps and steps-unorderedstepcmdinfostepresulttutorialinfo


Key elements to start

Before starting common elements I like:

title is often a heading for the topic, (also used by sections, examples, figures, tables)

shortdesc is an initial brief statement in a topic that does NOT repeat the title, it enhances it

prolog is metadata or information about a topic

manage content

www.publishingsmarter.com16

Domain elements

typographic relatedb, i, u, tt, sup, sub

programming relatedcodeph, codeblock, option, kwd, var, parmname, synph, oper, delim, sep, apiname, parml, plentry, pt, pd, syntaxdiagram, synblk, groupseq, groupchoice, groupcomp, fragment, fragref, synnote, synnoteref, repsep

software relatedmsgph, msgblock, msgnum, cmdname, varname, filepath, userinput, systemoutput

user interface relateduicontrol, wintitle, menucascade, shortcut, screen

utilities relatedimagemap, area, coord, shape


Develop any DITA topic type

Write the high-level structure, with at least a title, and (suggested) both a prolog and a good short description

Populate specific content as it is providedTask, Concept, Reference, Topic

The fantastic four of DITA

www.publishingsmarter.com 9:06

4


Tasks are core

Odds are people are doing things when they discover a need to look up docs

Tasks are the most likely place users turn

Non-DITA Purist: The procedural stuff you look up when you need to know how; often used by trainers or self-study guides


According to DITA: task

An answer to how that tells the user just what to do and the order in which to do it

Step-by-step instructions that enables a user to actually do something


DITA task structure

Structuretitle

shortdesc (or abstract)

prolog

taskbodyprerequisite

context

step

result

postrequisite

related links

nested topics

TASK


Concepts

If people are wondering why they should do something, or the benefits, then a concept is likely needed

Non-DITA Puristtells you what it is and why you want it with great background info


According to DITA: concept

Answers the question what is or why by detailing information about something

Initial information that users must know before they can successfully work

Supports the task by providing an explanation that is outside the scope of the task


DITA concept structure

Structure

title


prolog

conbodysections and examples

block-level elements

phrases and keywords

images and multimedia

related links

nested topics

CONCEPT

5


References

Non-DITA Purist: The tech stuff you look up when you know the big picture (concept)

specific details


According to DITA: reference

Quick access to factsTables, lists, alphabeticalUsers should be able to scan quickly and find informationOften technical or background information


DITA reference structure

Structuretitle


prolog

refbodysections and examples

syntax

tables

properties

related links

nested topics

REFERENCE


Topics

Non-DITA Purist

reference or often a starting point for specialization


According to DITA: topic

Top-level DITA element for a single subject or article

Starting point for all other base topic types

Used if no other topic type applies


DITA topic structure

Structure

title


prolog

bodysections and examples

block-level elements

phrases and keywords

images and multimedia

related links

nested topics

TOPIC

6

www.publishingsmarter.com31

Attributes

display-atts

scale, frame, expanse

id-atts

id, conref

select-atts

platform, product, audience, otherprops, importance, rev, status

topicref-attscollection-type, type, scope, locktitle, format, linking, toc, print, search, chunk

univ-attsall select-atts, all id-atts, translate, xml:lang

Control and Publish DITA

Beyond writing: Sharing, managing, linking, and publishing topics


Starting points beyond writing

conref: Content that is referenced or reused within topcsmap: Doc with info about topic relationships as well as optional links, groups, and navigation functionsreltable: Used to manage relationships between topics (beyond parent/child) when used in a mapditaval: Publishing or output information used when converting DITA to print or online outputs


According to DITA: conref

Reused content (content reference)

References to other content

A way to link to information and share it across projects if needed


Benefits of a conref

Create once

Use often

Update source, all are updated to match


Definition of a map

Describes relationships between resources (such as DITA topics)

References to resources organized into hierarchies and groups

A way to express relationships in a single common format

7


Map structure

Structure

title

topicrefs (can be nested)

topicmeta (more topic info when in a specific map)

topichead (for extra titles)

topicgroup (for organizing and inheriting properties)

reltables (map level navigation functions)

DITAMAP


Definition of a reltable

Describes non-hierarchical relationships between resources (such as DITA topics)

References resources in a table model (often

concept/task/reference)

Non-DITA Purist: A bit like manually building a group of related topics in help, but better


Benefit of a reltable

Plan content linking

Combine topics for linking and navigation

Not stored in the topic

Can be map specific

Can be shared


What is a ditaval?

Conditional processing profile

Identifies values to conditionally process for a particular output, build, etc

Non-DITA Purist: Sort of like conditional content, or using show/hide settings but better


How to develop a ditaval?

ID content with attributesCreate ditaval files, and use to publishIf publishing Windows XP only vs Windows 7 only

<val><prop action='exclude att='platform' val='Win7' ></prop></val>or

<val><prop action='exclude' att='platform' val='XP'></ prop></val>

Visualize the Process

How might DITA work?

8


Plan a collection of topics

Assume the following:Word processor

Users are newer writers

Experience level is novice to general

Familiarity with Windows and very basic tasks assumed

Main topics may include some/all:

Product Overview

Launch

Create

Import

Save / Save As

Close / Open

Delete


Assign topic types

Take list of topics and assign types

Consider primary DITA ideas

Task

Concept

Reference

Some may have more than one topic type


Develop a map

At a high level, decide on primary goal

Make that goal clear

Add supporting content

Maps as org charts

Manage Files

C_Manage

T_Create

C_SaveAs

T_Save

T_SaveAsR_Format

T_Close

T_Open


Maps as a TOC

www.publishingsmarter.com47 8:06 www.publishingsmarter.com48 8:07

Maps for planning content

ManageFiles

C_Manage T_Create C_SaveAs

T_Save T_SaveAs

R_Formats T_Close T_Open

9


Map and topics

ManageFiles


T_Save T_SaveAs



Map and topics

ManageFiles


T_Save T_SaveAs



Map and topics

ManageFiles


T_Save T_SaveAs



Map and topics

ManageFiles


T_Save T_SaveAs



Map and topics

ManageFiles


T_Save T_SaveAs



Map and relationships

ManageFiles


T_Save T_SaveAs


10



ManageFiles


T_Save T_SaveAs




ManageFiles


T_Save T_SaveAs




ManageFiles


T_Save T_SaveAs




ManageFiles


T_Save T_SaveAs




ManageFiles


T_Save T_SaveAs



Relationship table sample

Reason/Note Task Concept ReferenceFiles that have been created likely should be saved

T_SaveAs

T_Save

T_Create

C_SaveAs

11




T_SaveAs

T_Save

T_Create

C_SaveAs




T_SaveAs

T_Save

T_Create

C_SaveAs


Reltable linking to concept


T_SaveAs

T_Save

T_Create

C_SaveAs R_Formats


Title/shortdesc samples

Create documents (file: T_Create)New electronic files can be produced as required.

Saving with a specific name (file: C_SaveAs)Electronic files that have not yet been saved can be saved to specific locations with specific names; even files that have been previously saved can be updated with a new name or location.

File formats (file: R_Formats)Many common types of documents can be worked with.







Automated prototypes (1/2)

12


Map and topics

ManageFiles


T_Save T_SaveAs

R_Format T_Close T_Open


Map and topics

ManageFiles


T_Save R_Formats

T_SaveAs T_Close T_Open











Attributes and output

ManageFiles


T_Save R_Formats

T_SaveAs T_Close T_Open

13


Conditional inclusion/publish

ManageFiles


T_Save R_Formats

T_SaveAs T_Close T_OpenT_Delete

(audience=admin)

Comparison of the TOC


Core ideas within DITA


Maps


Reltables


Topics


Specializations


Contact Information

Contact Bernard

[email protected]

Call 905 833 8448

Twitter: aschwanden or aschwanden4stc

LinkedIn



Bonus Materials

If we are quick, then the following bonuses

Build a better mouse doc

ID the audience, the problems they want to resolve

Build a map and reltable

Create content

Create many outputs


mailto:[email protected]

14

Build a better mouse doc

And the world will beat a path to your doc team


Document planning

Imagine a publication that is very simple

Documentation for a remote mouse

It has basic or no documentation

A rough idea is suggested to management

An outline is created

Stub files and a map are drafted


Document development

Topics are updated

Drafts are provided along the way for review

Very informal system early on

Can implement a CMS over time


Who the user is

Mouse Tasks Performed (Generalize yes/no)

Audience Install/Config Use

IT Staff Yes

No

No

Presenter No Yes

No


Our users: Doing/Seeking

Mouse Model of the User


IT Staff Install it on a PC

Test the operations

Configure settings/speed

Where can I get a driver?

Presenter How do I run a presentation?

What functions are built in?

Will it function like a mouse?

Why are functions failing?


Problems they may encounter

Mouse Problems faced when they need to


IT Staff How long will it take

How much config is there

Will this OS support it

What if we lose the receiver?

Do I have to train users?

Presenter Dead batteries

Slideshow issues (advance, build, blackout/whiteout)

Overly sensitive to the touch

15


List of topics (sample)

Topic Topic TopicComputer requirements Adjust remote sensitivity How to order

Shipping cost, product cost, warranty costs

Drivers (OS specific) Installation

First time use Regular use Test the install

Double click speed Scroll speed Button functions

Run a slideshow Troubleshooting

Replace the batteries Slideshow tips and tricks Components

Connect the mouse to a PC


List of topics with type (sample)

Topic and type Topic and type Topic and typeR_SystemRequirements T_TouchSensitivity, (and C_) T_OrderNow

R_Costs (shipping, product, warranty extension)

R_DriversAndDownloads T_Install

T_FirstTimeUse, (maybe C_) T_NormalUse T_InstallTest

T_AdjustDoubleClickSpeed T_AdjustScrollSpeed R_ButtonFunctions

T_RunSlideShow R_Troubleshooting R_SupportedOS

T_ChangeBatteries R_SlideshowTips R_Components

T_Connect


Presenter Map (sample)

T_NormalUse

T_Connect

C_FirstTimeUse

T_ChangeBatteries

R_Components

T_FirstTimeUse

T_NormalUse (cont)

T_RunSlideShow

R_SlideShowTips

R_ButtonFunctions

R_Troubleshooting

T_AdjustDoubleClick

T_TouchSensitivity


Distribution of content

In the map there are 12 topics

7 are tasks

1 is a concept

4 are reference


Develop reltables (sample)

Keep it simple, easy to understand

Focus on tasks early on

Notes Task Concept ReferencePeople may look up tips to find out what a button does, or refer to it during a presentation

T_RunSlideShow R_ButtonFunctions

R_SlideShowTIps

R_ButtonFunctions

Sometimes when connecting the batteries are dead

T_ChangeBatteries R_Troubleshooting


Initial title/file/shortdesc

Title/File Shortdesc

Regular mouse use (T_NormalUse)

Your day to day use of the mouse may include common tasks like scrolling and clicking, presenting slide shows, or using it as a laser pointer.

Connect the mouse (T_Connect)

Before you use the device, connect the receiver to your computer and ensure the connection is active.

Change batteries (T_ChangeBatteries)

When you first set up the device, or if connecting and a signal is not being sent, new batteries may have to be inserted.

Parts of the device (R_Components)

Two primary components of the device are detailed.

Using the remote mouse for the first time (C_FirstTimeUse)

The remote mouse has to be set up by following an initial installation process the first time it is used, and we recommend general familiarity with core ideas before starting.

Initial steps for new users (T_FirstTimeUse)

When you work with the device as a first time user there are a few core things you need to do to ensure your product works as intended.

16


Initial title/file/shortdesc

Title/File ShortdescPresent a slideshow (T_RunSlideShow)

PowerPoint presentations (and other slide show formats) can be run using the device as a mobile mouse allowing you to walk around while presenting.

Tips on running slide shows (R_SlideShowTips)

The functions of specific buttons change their specific functions when running a slideshow.

Device button functions (R_ButtonFunctions)

The functions of specific buttons allow scrolling, primary and secondary mouse clicks, and specific functions within different applications.

Troubleshooting (R_Troubleshooting)

The device should function as expected, but if it does not, troubleshooting information is available to self-test before contacting our technical support.

Change double click speed (T_AdjustDoubleClick)

If you find that the delay between two clicks is too fast, or not fast enough, you can adjust it to your personal preferences.

Change pointer speed (T_TouchSensitivity)

If you find that the device scrolls too fast, or not fast enough, you can adjust it to your personal preferences.


Now write

Begin with tasksIdentify any prerequisite as soon as possible

Identify the benefit of doing this

Write clear tasksEach step is self contained

A step has a basic command

Early steps have a result (to let the user know he is on the right path)

Add concept/reference as needed


Continue to write/update

Education

Introduction to DITA