1 Introduction to DITA Bernard Aschwanden www.publishingsmarter.com www.publishingsmarter.com 2 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 www.publishingsmarter.com 3 2:55 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 www.publishingsmarter.com 4 2:55 www.publishingsmarter.com 5 2:56 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
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
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
www.publishingsmarter.com3 2:55
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
www.publishingsmarter.com4 2:55
www.publishingsmarter.com5 2:56
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
www.publishingsmarter.com7 2:56
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
www.publishingsmarter.com8 2:56
www.publishingsmarter.com9 2:56
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
www.publishingsmarter.com10 2:56
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
www.publishingsmarter.com11 2:56
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
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
user interface relateduicontrol, wintitle, menucascade, shortcut, screen
utilities relatedimagemap, area, coord, shape
www.publishingsmarter.com17 9:19
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
www.publishingsmarter.com19 9:11
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
www.publishingsmarter.com20 9:11
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
www.publishingsmarter.com21 9:12
DITA task structure
Structuretitle
shortdesc (or abstract)
prolog
taskbodyprerequisite
context
step
result
postrequisite
related links
nested topics
TASK
www.publishingsmarter.com22 9:13
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
www.publishingsmarter.com23 9:14
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
www.publishingsmarter.com24 9:15
DITA concept structure
Structure
title
shortdesc (or abstract)
prolog
conbodysections and examples
block-level elements
phrases and keywords
images and multimedia
related links
nested topics
CONCEPT
5
www.publishingsmarter.com25 9:16
References
Non-DITA Purist: The tech stuff you look up when you know the big picture (concept)
specific details
www.publishingsmarter.com26 9:16
According to DITA: reference
Quick access to factsTables, lists, alphabeticalUsers should be able to scan quickly and find informationOften technical or background information
www.publishingsmarter.com27 9:17
DITA reference structure
Structuretitle
shortdesc (or abstract)
prolog
refbodysections and examples
syntax
tables
properties
related links
nested topics
REFERENCE
www.publishingsmarter.com28 9:17
Topics
Non-DITA Purist
reference or often a starting point for specialization
www.publishingsmarter.com29 9:18
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
www.publishingsmarter.com30 9:18
DITA topic structure
Structure
title
shortdesc (or abstract)
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
www.publishingsmarter.com33 9:07
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
www.publishingsmarter.com34 9:23
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
www.publishingsmarter.com35 9:24
Benefits of a conref
Create once
Use often
Update source, all are updated to match
www.publishingsmarter.com36 9:20
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
www.publishingsmarter.com37 9:20
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
www.publishingsmarter.com38 9:21
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
www.publishingsmarter.com39 9:23
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
www.publishingsmarter.com40 9:25
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
www.publishingsmarter.com41 9:27
How to develop a ditaval?
ID content with attributesCreate ditaval files, and use to publishIf publishing Windows XP only vs Windows 7 only
Reason/Note Task Concept ReferenceFiles that have been created likely should be saved
T_SaveAs
T_Save
T_Create
C_SaveAs
11
www.publishingsmarter.com61 8:09
Relationship table sample
Reason/Note Task Concept ReferenceFiles that have been created likely should be saved
T_SaveAs
T_Save
T_Create
C_SaveAs
www.publishingsmarter.com62 8:10
Relationship table sample
Reason/Note Task Concept ReferenceFiles that have been created likely should be saved
T_SaveAs
T_Save
T_Create
C_SaveAs
www.publishingsmarter.com63 8:10
Reltable linking to concept
Reason/Note Task Concept ReferenceFiles that have been created likely should be saved
T_SaveAs
T_Save
T_Create
C_SaveAs R_Formats
www.publishingsmarter.com64 8:10
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.
www.publishingsmarter.com65 8:11
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.
www.publishingsmarter.com66 8:11
Automated prototypes (1/2)
12
www.publishingsmarter.com67 8:11
Map and topics
ManageFiles
C_Manage T_Create C_SaveAs
T_Save T_SaveAs
R_Format T_Close T_Open
www.publishingsmarter.com68 8:11
Map and topics
ManageFiles
C_Manage T_Create C_SaveAs
T_Save R_Formats
T_SaveAs T_Close T_Open
www.publishingsmarter.com69 8:12
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.
www.publishingsmarter.com70 8:12
Automated prototypes (2/2)
www.publishingsmarter.com71 8:12
Automated prototypes (2/2)
www.publishingsmarter.com72 8:12
Attributes and output
ManageFiles
C_Manage T_Create C_SaveAs
T_Save R_Formats
T_SaveAs T_Close T_Open
13
www.publishingsmarter.com73 8:12
Conditional inclusion/publish
ManageFiles
C_Manage T_Create C_SaveAs
T_Save R_Formats
T_SaveAs T_Close T_OpenT_Delete
(audience=admin)
Comparison of the TOC
www.publishingsmarter.com74 8:12
Core ideas within DITA
www.publishingsmarter.com75 8:59
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
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
www.publishingsmarter.com90 9:39
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
www.publishingsmarter.com91 9:39
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.
www.publishingsmarter.com92 9:40
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)