1Introduction to DITABernard Aschwandenwww.publishingsmarter.comwww.publishingsmarter.com2 2:55Bernard AschwandenPresident of Publishing SmarterWorked in docs and training since 1992Consultant and trainer in CMS, XML, DITA,and publishing technologiesSTC Toronto Community Past Presidentwww.publishingsmarter.com3 2:55Publishing SmarterWorks with clients to improve contentcreation, management, and distributionworkflowsProvides content analysis, legacy fileconversion, training, and supportMain goals are to reduce production costs,improve document quality, and increaseemployee productivityLearner outcomeUnderstand core DITAPresent your team clear information aboutDITA and the pros and cons it offersSee DITA applied to real world doc examplesDeliver the right content, to the rightaudience, at the right time, and in the rightformatwww.publishingsmarter.com4 2:55www.publishingsmarter.com5 2:56My disclaimerI will be making blanket statements aboutDITA to keep things simpleNot all that I tell you will be 100% DITA, butSlides are a reference, they go by quicklyBonus materials may also be coveredAbout DITASumming up a complex idea in asfew slides as possible
2DITA should matter to youA growing standard with vendor supportAdobe, JustSystems, Oxygen, Quark, third-partyWord support, and much moreMore companies looking for DITA skillsNot just structured writing; best practices:Planning contentOrganizing informationDeveloping relationshipsUsing automation where it makes sensewww.publishingsmarter.com7 2:56Setting the stageMost of the people in attendance have likelyheard of DITAThere is a very short overview of DITA to puteveryone into a similar mindset to startSummation and open QnA sessionBonus materials as time allowswww.publishingsmarter.com8 2:56www.publishingsmarter.com9 2:56DITA in a single slideD is for DarwinIT is for Information TypingA is for ArchitectureDITA is primarily about Topic, Maps, SpecializationsSome included specializations includeconcept, reference, task, glossary (topic based)bookmap (map based)various domains (software, programming)Core ideas within DITAwww.publishingsmarter.com10 2:56MapsUsed to plan, organize, andpublishReltablesBuild relationships betweeninfo in mapsTopicsTypes of info in a map, generallyas task, concept, or referenceSpecializationsCustomize as needed if otheroptions are exhaustedBehind the sceneswww.publishingsmarter.com11 2:56MapsUsed to plan, organize, andpublishReltablesBuild relationships betweeninfo in mapsTopicsTypes of info in a map, generallyas task, concept, or referenceSpecializationsCustomize as needed if otheroptions are exhaustedAttributesWriting DITAKey ideas that writers should focuson when starting
3Starting points for writerstopic: A meaningful, stand alone unit ofinformation, minimalist, well writtentask: Procedural details (step-by-stepinstructions)concept: Background info users need toknowreference: Quick access to factsattributes: Metadata used to further defineelementswww.publishingsmarter.com 9:06 www.publishingsmarter.com14Commonly used elementsparagraph elementstgroup and table elementsbody related elementsbodyconbodyrefbodytaskbodysection and example elementsxref elementlist elementsulollifigure and image elementstask related elementsprereqcontextstepsresultexamplepostreqsteps related elementssteps and steps-unorderedstepcmdinfostepresulttutorialinfowww.publishingsmarter.com15 9:09Key elements to startBefore starting common elements I like:title is often a heading for the topic, (also used bysections, examples, figures, tables)shortdesc is an initial brief statement in a topicthat does NOT repeat the title, it enhances itprolog is metadata or information about a topicmanage contentwww.publishingsmarter.com16Domain elementstypographicrelatedb, i, u, tt, sup, subprogramming relatedcodeph, codeblock, option,kwd, var, parmname, synph,oper, delim, sep, apiname,parml, plentry, pt, pd,syntaxdiagram, synblk,groupseq, groupchoice,groupcomp, fragment,fragref, synnote, synnoteref,repsepsoftware relatedmsgph, msgblock, msgnum,cmdname,varname, filepath,userinput, systemoutputuser interface relateduicontrol, wintitle,menucascade,shortcut,screenutilitiesrelatedimagemap, area, coord,shapewww.publishingsmarter.com17 9:19Develop any DITA topic typeWrite the high-level structure, with at least atitle, and (suggested) both a prolog and agood short descriptionPopulate specific content as it is providedTask, Concept, Reference, TopicThe fantastic four of DITAwww.publishingsmarter.com 9:06
4www.publishingsmarter.com19 9:11Tasks are coreOdds are people are doing things when theydiscover a need to look up docsTasks are the most likely place users turnNon-DITA Purist: The procedural stuff youlook up when you need to know how; oftenused by trainers or self-study guideswww.publishingsmarter.com20 9:11According to DITA: taskAn answer to how that tells the user justwhat to do and the order in which to do itStep-by-step instructions that enables a userto actually do somethingwww.publishingsmarter.com21 9:12DITA task structureStructuretitleshortdesc (or abstract)prologtaskbodyprerequisitecontextstepresultpostrequisiterelated linksnested topicsTASKwww.publishingsmarter.com22 9:13ConceptsIf people are wondering why they should dosomething, or the benefits, then a concept islikely neededNon-DITA Puristtells you what it is and why you want it withgreat background infowww.publishingsmarter.com23 9:14According to DITA: conceptAnswers the question what is or why bydetailing information about somethingInitial information that users must knowbefore they can successfully workSupports the task by providing anexplanation that is outside the scope of thetaskwww.publishingsmarter.com24 9:15DITA concept structureStructuretitleshortdesc (or abstract)prologconbodysections and examplesblock-levelelementsphrases and keywordsimages and multimediarelated linksnested topicsCONCEPT
5www.publishingsmarter.com25 9:16ReferencesNon-DITA Purist: The tech stuff you look upwhen you know the big picture (concept)specific detailswww.publishingsmarter.com26 9:16According to DITA: referenceQuick access to factsTables, lists, alphabeticalUsers should be able to scan quickly and findinformationOften technical or background informationwww.publishingsmarter.com27 9:17DITA reference structureStructuretitleshortdesc (or abstract)prologrefbodysections and examplessyntaxtablespropertiesrelated linksnested topicsREFERENCEwww.publishingsmarter.com28 9:17TopicsNon-DITA Puristreference or often a starting point forspecializationwww.publishingsmarter.com29 9:18According to DITA: topicTop-level DITA element for a single subject orarticleStarting point for all other base topic typesUsed if no other topic type applieswww.publishingsmarter.com30 9:18DITA topic structureStructuretitleshortdesc (or abstract)prologbodysections and examplesblock-levelelementsphrases and keywordsimages and multimediarelated linksnested topicsTOPIC
6www.publishingsmarter.com31Attributesdisplay-attsscale, frame, expanseid-attsid, conrefselect-attsplatform, product,audience, otherprops,importance, rev, statustopicref-attscollection-type,type,scope, locktitle, format,linking, toc, print,search, chunkuniv-attsall select-atts, all id-atts,translate, xml:langControl and Publish DITABeyond writing: Sharing, managing,linking, and publishing topicswww.publishingsmarter.com33 9:07Starting points beyond writingconref: Content that is referenced or reused withintopcsmap: Doc with info about topic relationships as wellas optional links, groups, and navigation functionsreltable: Used to manage relationships betweentopics (beyond parent/child) when used in a mapditaval: Publishing or output information usedwhen converting DITA to print or online outputswww.publishingsmarter.com34 9:23According to DITA: conrefReused content (content reference)References to other contentA way to link to information and share itacross projects if neededwww.publishingsmarter.com35 9:24Benefits of a conrefCreate onceUse oftenUpdate source, all areupdated to matchwww.publishingsmarter.com36 9:20Definition of a mapDescribes relationships between resources(such as DITA topics)References to resources organized intohierarchies and groupsA way to express relationships in a singlecommon format
7www.publishingsmarter.com37 9:20Map structureStructuretitletopicrefs (can be nested)topicmeta (more topic infowhen in a specific map)topichead (for extra titles)topicgroup (for organizing andinheriting properties)reltables (map levelnavigation functions)DITAMAPwww.publishingsmarter.com38 9:21Definition of a reltableDescribes non-hierarchical relationshipsbetween resources (such as DITA topics)References resources in a table model (oftenconcept/task/reference)Non-DITA Purist: A bit like manually building agroup of related topics in help, but betterwww.publishingsmarter.com39 9:23Benefit of a reltablePlan content linkingCombine topics forlinking and navigationNot stored in the topicCan be map specificCan be sharedwww.publishingsmarter.com40 9:25What is a ditaval?Conditional processing profileIdentifies values to conditionally process for aparticular output, build, etcNon-DITA Purist: Sort of like conditionalcontent, or using show/hide settings butbetterwww.publishingsmarter.com41 9:27How 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 ProcessHow might DITA work?
8www.publishingsmarter.com43 8:06Plan a collection of topicsAssume the following:Word processorUsers are newer writersExperience level isnovice to generalFamiliarity withWindows and very basictasks assumedMain topics mayinclude some/all:Product OverviewLaunchCreateImportSave / Save AsClose / OpenDeletewww.publishingsmarter.com44 8:06Assign topic typesTake list of topics and assign typesConsider primary DITA ideasTaskConceptReferenceSome may have more than one topic typewww.publishingsmarter.com45 8:06Develop a mapAt a high level, decide on primary goalMake that goal clearAdd supporting contentMaps as org chartsManageFilesC_ManageT_CreateC_SaveAsT_SaveT_SaveAsR_FormatT_CloseT_Openwww.publishingsmarter.com46 8:06Maps as a TOCwww.publishingsmarter.com47 8:06 www.publishingsmarter.com48 8:07Maps for planning contentManageFilesC_Manage T_Create C_SaveAsT_Save T_SaveAsR_Formats T_Close T_Open
9www.publishingsmarter.com49 8:07Map and topicsManageFilesC_Manage T_Create C_SaveAsT_Save T_SaveAsR_Formats T_Close T_Openwww.publishingsmarter.com50 8:07Map and topicsManageFilesC_Manage T_Create C_SaveAsT_Save T_SaveAsR_Formats T_Close T_Openwww.publishingsmarter.com51 8:07Map and topicsManageFilesC_Manage T_Create C_SaveAsT_Save T_SaveAsR_Formats T_Close T_Openwww.publishingsmarter.com52 8:08Map and topicsManageFilesC_Manage T_Create C_SaveAsT_Save T_SaveAsR_Formats T_Close T_Openwww.publishingsmarter.com53 8:08Map and topicsManageFilesC_Manage T_Create C_SaveAsT_Save T_SaveAsR_Formats T_Close T_Openwww.publishingsmarter.com54 8:08Map and relationshipsManageFilesC_Manage T_Create C_SaveAsT_Save T_SaveAsR_Formats T_Close T_Open
10www.publishingsmarter.com55 8:08Map and relationshipsManageFilesC_Manage T_Create C_SaveAsT_Save T_SaveAsR_Formats T_Close T_Openwww.publishingsmarter.com56 8:08Map and relationshipsManageFilesC_Manage T_Create C_SaveAsT_Save T_SaveAsR_Formats T_Close T_Openwww.publishingsmarter.com57 8:08Map and relationshipsManageFilesC_Manage T_Create C_SaveAsT_Save T_SaveAsR_Formats T_Close T_Openwww.publishingsmarter.com58 8:09Map and relationshipsManageFilesC_Manage T_Create C_SaveAsT_Save T_SaveAsR_Formats T_Close T_Openwww.publishingsmarter.com59 8:09Map and relationshipsManageFilesC_Manage T_Create C_SaveAsT_Save T_SaveAsR_Formats T_Close T_Openwww.publishingsmarter.com60 8:09Relationship table sampleReason/Note Task Concept ReferenceFiles that have beencreated likely should besavedT_SaveAsT_SaveT_CreateC_SaveAs
11www.publishingsmarter.com61 8:09Relationship table sampleReason/Note Task Concept ReferenceFiles that have beencreated likely should besavedT_SaveAsT_SaveT_CreateC_SaveAswww.publishingsmarter.com62 8:10Relationship table sampleReason/Note Task Concept ReferenceFiles that have beencreated likely should besavedT_SaveAsT_SaveT_CreateC_SaveAswww.publishingsmarter.com63 8:10Reltable linking to conceptReason/Note Task Concept ReferenceFiles that have beencreated likely should besavedT_SaveAsT_SaveT_CreateC_SaveAs R_Formatswww.publishingsmarter.com64 8:10Title/shortdesc samplesCreate 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 canbe saved to specific locations with specificnames; even files that have been previouslysaved can be updated with a new name orlocation.File formats (file: R_Formats)Many common types of documents can beworked with.www.publishingsmarter.com65 8:11Title/shortdesc samplesCreate 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 canbe saved to specific locations with specificnames; even files that have been previouslysaved can be updated with a new name orlocation.File formats (file: R_Formats)Many common types of documents can beworked with.www.publishingsmarter.com66 8:11Automated prototypes (1/2)
12www.publishingsmarter.com67 8:11Map and topicsManageFilesC_Manage T_Create C_SaveAsT_Save T_SaveAsR_Format T_Close T_Openwww.publishingsmarter.com68 8:11Map and topicsManageFilesC_Manage T_Create C_SaveAsT_Save R_FormatsT_SaveAs T_Close T_Openwww.publishingsmarter.com69 8:12Title/shortdesc samplesCreate 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 canbe saved to specific locations with specificnames; even files that have been previouslysaved can be updated with a new name orlocation.File formats (file: R_Formats)Many common types of documents can beworked with.www.publishingsmarter.com70 8:12Automated prototypes (2/2)www.publishingsmarter.com71 8:12Automated prototypes (2/2)www.publishingsmarter.com72 8:12Attributes and outputManageFilesC_Manage T_Create C_SaveAsT_Save R_FormatsT_SaveAs T_Close T_Open
13www.publishingsmarter.com73 8:12Conditional inclusion/publishManageFilesC_Manage T_Create C_SaveAsT_Save R_FormatsT_SaveAs T_Close T_OpenT_Delete(audience=admin)Comparison of the TOCwww.publishingsmarter.com74 8:12Core ideas within DITAwww.publishingsmarter.com75 8:59MapsUsed to plan, organize, andpublishReltablesBuild relationships betweeninfo in mapsTopicsTypes of info in a map, generallyas task, concept, or referenceSpecializationsCustomize as needed if otheroptions are exhaustedContact InformationContact Bernardbernard@publishingsmarter.comCall 905 833 8448Twitter: aschwanden or aschwanden4stcLinkedInwww.publishingsmarter.com 9:06www.publishingsmarter.com 9:06Bonus MaterialsIf we are quick, then the following bonusesBuild a better mouse docID the audience, the problems they want toresolveBuild a map and reltableCreate contentCreate many outputswww.publishingsmarter.com 9:06
14Build a better mouse docAnd the world will beat a path toyour doc teamwww.publishingsmarter.com80 9:28Document planningImagine a publication that is very simpleDocumentation for a remote mouseIt has basic or no documentationA rough idea is suggested to managementAn outline is createdStub files and a map are draftedwww.publishingsmarter.com81 9:31Document developmentTopics are updatedDrafts are provided along the way for reviewVery informal system early onCan implement a CMS over timewww.publishingsmarter.com82 9:32Who the user isMouse Tasks Performed (Generalize yes/no)Audience Install/Config UseIT Staff Yes No NoPresenter No Yes Nowww.publishingsmarter.com83 9:32Our users: Doing/SeekingMouse Model of the UserAudience Install/Config UseIT Staff Install it on a PCTest the operationsConfigure settings/speedWherecan 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?www.publishingsmarter.com84 9:33Problems they may encounterMouse Problems faced when they need toAudience Install/Config UseIT Staff How long will it takeHow much config is thereWill this OS support itWhat if we lose the receiver?Do I have to train users?Presenter Dead batteriesSlideshow issues (advance,build, blackout/whiteout)Overlysensitive to the touch
15www.publishingsmarter.com85 9:34List of topics (sample)Topic Topic TopicComputer requirements Adjust remote sensitivity How to orderShipping cost, product cost,warrantycostsDrivers (OS specific) InstallationFirst time use Regular use Test the installDouble click speed Scroll speed Button functionsRun a slideshow TroubleshootingReplace the batteries Slideshow tips and tricks ComponentsConnect the mouse to a PCwww.publishingsmarter.com86 9:34List of topics with type (sample)Topic and type Topic and type Topic and typeR_SystemRequirements T_TouchSensitivity, (and C_) T_OrderNowR_Costs (shipping, product,warrantyextension)R_DriversAndDownloads T_InstallT_FirstTimeUse, (maybe C_) T_NormalUse T_InstallTestT_AdjustDoubleClickSpeed T_AdjustScrollSpeed R_ButtonFunctionsT_RunSlideShow R_Troubleshooting R_SupportedOST_ChangeBatteries R_SlideshowTips R_ComponentsT_Connectwww.publishingsmarter.com87 9:37Presenter Map (sample)T_NormalUseT_ConnectC_FirstTimeUseT_ChangeBatteriesR_ComponentsT_FirstTimeUseT_NormalUse (cont)T_RunSlideShowR_SlideShowTipsR_ButtonFunctionsR_TroubleshootingT_AdjustDoubleClickT_TouchSensitivitywww.publishingsmarter.com88 9:38Distribution of contentIn the map there are 12 topics7 are tasks1 is a concept4 are referencewww.publishingsmarter.com89 9:39Develop reltables (sample)Keep it simple, easy to understandFocus on tasks early onNotes Task Concept ReferencePeople may look uptips to find out what abutton does, or referto it during apresentationT_RunSlideShow R_ButtonFunctionsR_SlideShowTIpsR_ButtonFunctionsSometimes whenconnecting thebatteries are deadT_ChangeBatteries R_Troubleshootingwww.publishingsmarter.com90 9:39Initial title/file/shortdescTitle/File ShortdescRegular mouse use(T_NormalUse)Your day to day use of the mouse may include common tasks like scrolling andclicking, 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 theconnection 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 remotemouse for the firsttime (C_FirstTimeUse)The remote mouse has to be set up by following an initial installation process thefirst time it is used, and we recommend general familiarity with core ideas beforestarting.Initial steps for newusers (T_FirstTimeUse)When you work with the device as a first time user there are a few core things youneed to do to ensure your product works as intended.
16www.publishingsmarter.com91 9:39Initial title/file/shortdescTitle/File ShortdescPresent a slideshow(T_RunSlideShow)PowerPoint presentations (and other slide show formats) can be run using thedevice as a mobile mouse allowing you to walk around while presenting.Tips on running slideshows(R_SlideShowTips)The functions of specific buttons change their specific functions when running aslideshow.Device buttonfunctions(R_ButtonFunctions)The functions of specific buttons allow scrolling, primary and secondary mouseclicks, and specific functions within different applications.Troubleshooting(R_Troubleshooting)The device should function as expected, but if it does not, troubleshootinginformation is available to self-test before contacting our technical support.Change double clickspeed(T_AdjustDoubleClick)If you find that the delay between two clicks is too fast, or not fast enough, you canadjust 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 toyour personal preferences.www.publishingsmarter.com92 9:40Now writeBegin with tasksIdentify any prerequisite as soon as possibleIdentify the benefit of doing thisWrite clear tasksEach step is self containedA step has a basic commandEarly steps have a result (to let the user know he is onthe right path)Add concept/reference as neededwww.publishingsmarter.com93 10:13Continue to write/update