Thetwomainunitsof authoringinDITAaretopicsand maps.Eachcanbe extendedintonewstructural typesand domainsthrough specialization.
DITA topics
DITAtopics arethebasicunitsofDITAcontent.Eachtopicshouldbe organizedarounda singlesubject.
What are topics?
Atopicisa unitofinformationwitha titleand content,shortenoughtobespecific toasinglesubjector answerasingle question,butlongenoughtomakesenseonitsown andbe authoredasaunit.
InDITA,atopicisthebasic unitofauthoringand ofreuse.Adocumentmaycontainonetopicor
multipletopics,and adocumenttypemaysupport authoringoneormanykindsoftopics.Butregardless ofwheretheyoccur,alltopics havethesamebasic structureandcapabilities. Books,PDFfiles,Websites, andhelpsets, forexample,canall beconstructedfromthesameset ofunderlyingtopiccontent,although theremaybe sometopicsthatareuniquetoaparticulardeliverable,andtheorganizationoftopicsmay differtotakeadvantageoftheuniquecapabilitiesofeachdeliverymechanism.
Referenceinformationisinherentlytopic-oriented,since itrequiresinformationtobe modularand self-containedforthesakeofretrievability.
Topic-orientedauthoringforconceptualandtaskinformationhasitsrootsin Minimalism,aninstructional designtechniquefirstespoused byJohnCarroll.Theminimalistapproachtoinformationdesignfocusses onidentifyingthesmallestamountofinstructionthatallowsforthesuccessfulcompletionofatask,or thatprovidesbasicknowledgeofaconcept.Readers havegoals, andtheywanttoachievethosegoalsas quicklyaspossible.Generally,readersdon’twanttoread informationjustforthepleasureofreading.
Theyarereadingtolearnortodosomething.
SomeofthekeyprinciplesofMinimalismare:
v Supportactions.Letpeopleactastheylearn,and letthempursuethegoalstheywantto accomplish.
v Documenttasks,nottoolsorfunctions.
v Helpreadersanticipateandavoiderrors.
v Letreadersexplore.Theydon’tneed explainedwhattheycandiscoverforthemselves.
WhileDITA’stopic-orientedapproachhasitsrootsininstructionaldesign,thetopic-based approachcan beusefulforanyinformationthathashumanreadersanda consistentstructure.
Why topics?
Topicsarethebasisforhigh-qualityinformation.They shouldbeshortenoughtobe easilyreadable,but longenoughtomake senseontheirown.
Byorganizingcontentintotopics,authorscanachieveseveralgoalssimultaneously:
v Contentisreadableevenwhenaccessedfromanindexorsearch,notjustwhen readinsequenceas partofa chapter.Sincemostreadersdon’tread informationend-to-end,it’sgoodinformationdesignto makesureeachunitofinformationcanbe readonitsown togivejust-in-timehelp.
v Contentcanbeorganized differentlyforonline andprintpurposes.Authorscancreatetaskflowsand concepthierarchiesforonlineorientation,andstillhavea print-friendlycombinedhierarchythathelps peoplewhodowantanorganized readingflow.
7
v Contentcanbereused indifferentcollections.Sincethetopiciswritten tomakesensewhenaccessed randomly(asbysearch),it shouldalso makesensewhenincludedaspartofdifferentproduct deliverables,soauthorscanrefactorinformationasneeded, includingjustthetopicsthatapplyfor eachreusescenario.
Topicsaresmallenoughtoprovidelotsofopportunitiesforreuse,butlargeenoughtobe coherently authoredandread. WhileDITAsupportsreuse belowthetopiclevel,thisrequiresconsiderablymore thoughtand review,since topicsassembledoutofsmallerchunksoftenrequire editingto makethem flowproperly.By contrast,sincetopicsarealreadyorganized aroundasinglesubject,authorscan organizea setoftopicslogically andget anacceptableflowbetweenthem,since transitionsfromsubject tosubjectdon’tneedtobeasseamless astheexplanations withinasingle subject.
Information typing
Informationtypingisthepracticeof identifyingtypesoftopicsthatcontaindistinctkindsinformation, suchasconcepts, tasks,andreferenceinformation.Topicsthatanswerdifferentkindsofquestionscanbe categorizedasdifferentinformationtypes.The basetopictypesprovided byDITA(agenerictopic,plus concept,task,andreference)provideausablestartersetthatcanbeadoptedforimmediateauthoring.
Classifyinginformationbytype helpsauthors:
v
Designnew informationmoreeasilyandconsistently.
v Ensuretherightdesigngetsusedforthekindofinformation(retrieval-orientedstructureslike tables forreferenceinformation,simplesequencesof stepsfortaskinformation)
v Focusontasks.
v Factoroutsupportingconceptsandreferenceinformationintoothertopics,wherethey canbe readif requiredandignoredif not.
v Eliminateunimportantorredundantinformation.Identifycommonorreusable subjects.
Informationtypingispartofthegeneralauthoringapproach calledstructuredwriting,whichisused acrossthetechnicalauthoringindustrytoimproveinformationquality.Itisbasedonextensiveresearch andexperience,includingRobert Horn’sInformationMapping,andHughesAircraft’sSTOP(Sequential ThematicOrganization ofProposals).
InformationtypesinDITAareexpressedastopictypes. ThebasetopictypesprovidedbyDITAcanbe usedasa baseforfurtherspecialization.Newinformationtypesthatrequiredifferentstructuresand semanticsaredirectlysupportedbytopictypemodules,eachof whichdefinesthespecific markupand structuralrulesrequiredtodescribea particulartypeoftopic.Thesemodulescanthenbe integratedinto documenttypestosupport authoringinformation-typed topics.
Topic structure
Alltopics havethesamebasicstructure,regardlessoftopictype:title, description,prolog, andbody.
AllDITAtopicsmusthaveanID, atitle, andabody.Topicstructurescanconsistof thefollowingparts:
Topicelement
Requiredidattribute,containsallotherelements Title Thesubjectofthetopic.
Alternatetitles
Titlesspecificallyforuseinnavigationorsearch.Whennotprovided,thebase titleisusedforall contexts.
Shortdescription
Ashortdescriptionofthetopic.Usedbothintopiccontent,ingeneratedsummariesthatinclude
thetopic,andin linkstothetopic.Whileshortdescriptionsaren’trequired,theycanmakea dramaticdifferencetotheusability ofaninformationset,andshouldgenerallybeprovidedfor alltopics.
Prolog Containerforvariouskindsoftopicmetadata, suchaschangehistory,audience, product,andso on.
Body Theactualtopiccontent:paragraphs, lists,sections-whatever theinformationtype allows.
Relatedlinks
Linkstoothertopics.Whenanauthorcreates alinkaspartofa topic,thetopicbecomes
dependentontheothertopicbeingavailable.Toreducedependenciesbetweentopics andthereby increasethereusabilityofeachtopic,authorscanuseDITAmapstodefineandmanage links betweentopics, insteadofembeddinglinksdirectlyineachrelatedtopic.
Nestedtopics
Topicscanbedefinedinsideothertopics.Nestingcanresultincomplex documentsthatareless usableand lessreusable,andshouldbeusedcarefully.Itismoreoftenappropriateforreference information,whichcansupportlongerdocumentsorganized intomultipletopics forscanning andretrieval.
Topic content
Alltopics,regardlessoftopictype,buildonthesamecommonstructures.
Topicbodies
Whilealltopictypeshavethesameelementsfortitle,shortdescription, andprolog,theyeach allowdifferentcontentintheirbody.
Sectionsandexamples
Sectionsandexamples canbe containedonlybythebodyofatopic.They cannotnest.Theycan containblock-levelelementslikeparagraphs,phrase-levelelementslikeAPInames,or text.
Block-levelelements
Paragraphs,lists,andtablesarekindsof″block″elements.Asa classofcontent,theycancontain otherblocks,phrases,ortext,thoughtherulesvaryforeachstructure.
Phrasesandkeywords
Authorscanintermixmarkupwith textwhenthey needtoidentifypartofa paragraphoreven partofa sentenceashavingspecialsignificance.Phrasescanusuallycontainotherphrasesand keywordsaswellastext. Keywordscanonlycontaintext.
Images
Authorscaninsertimagesusingtheimageelement. Imagescanbe usedat theblocklevel,for exampletoshowscreencapturesordiagrams,orat thephraselevel,forexample toshowwhat iconsortoolbarbuttonslooklike.
Multimedia
Authorscancreatemultimediaforonline informationusingtheobjectelement,forexampleto displaySVGdiagramsthatcanberotatedand explored.
Topic modules
Therearethreebasic modulesintopic:fortables,formetadata, andforeverythingelse.
tblDecl.mod(DTD)
tblDeclMod.xsd,tblDeclGrp.xsd(Schema)
Definestheelementsforauthoringtables, basedontheCALStablemodelbutwith some DITA-specificextensions.
Chapter3.DITAmarkup 9
metaDecl.mod(DTD)
metaDeclMod.xsd,metaDeclGrp.xsd(Schema)
Definesmetadataelements.AlsousedbyDITAmaps,wheremetadatacanbedefinedfor multipletopicsat once.
topicAttr.mod,topicDefn.ent(DTDonly-foldedintootherschemafiles)) CommonDITAattributesand entities.
xml.xsd,ditaarch.xsd(Schemaonly-foldedintootherDTDfiles)
CommonXMLattributes andtheDITAarchitectureversion attribute topic.mod(DTD)
topicMod.xsd,topicGrp.xsd(Schema)
Definestherestoftheelementsinatopic.
Concepts
DITAconcept topicsanswer″Whatis...″questions.They includea body-levelelementwithabasic topic structure,includingsectionsandexamples.
Whyconcepts?
Conceptsprovidebackgroundthathelpsreadersunderstandessentialinformationabouta product, interface,ortask.Often,aconcept isanextended definitionofa majorabstractionsuchasaprocess or function.Conceptualinformationmayexplainaproductandhowit fitsintoitscategoryofproducts.
Conceptualinformationhelpsuserstomaptheirexistingknowledgetotasksandotheressential informationaboutaproductorsystem.
Conceptstructure
The<concept>elementisthetop-levelelementfora DITAconcept topic.Everyconcept containsa<title>
anda <conbody>andoptional <titlealts>,<shortdesc>,<prolog>,and<related-links>.
The<conbody>elementisthemainbody-level elementfora concept.Likethebodyelementofa general topic,<conbody>allowsparagraphs, lists,andotherelementsaswellassectionsand examples.But
<conbody>hasaconstraintthata sectionoranexamplecanbe followedonlybyothersectionsor examples.
Hereisanexampleofa simpleconcepttopic.
<concept id="concept">
<title>Bird Calling</title>
<conbody>
<p>Bird calling attracts birds.</p>
<example>
<p>Bird calling requires learning:</p>
<ul>
<li>Popular and classical bird songs</li>
<li>How to whistle like a bird</li>
</ul>
</example>
</conbody>
</concept>
Modules
concept.mod (DTD)
conceptMod.xsd, conceptGrp.xsd(Schema)
Tasks
Tasktopicsanswer″Howdo I?″ questions,andhaveawell-definedstructure thatdescribeshowto completea proceduretoaccomplisha specificgoal.
Whytasks?
Tasksaretheessentialbuildingblocks forprovidingprocedureinformation.Atasktopicanswers the
″HowdoI?″questionbyprovidingprecisestep-by-step instructionsdetailingwhattodoand theorderin whichtodoit.Thetasktopicincludessectionsfordescribing thecontext,prerequisites, expectedresults, andotheraspectsofatask.
Taskstructure
The<task>elementisthetop-levelelementfora tasktopic.Everytasktopiccontainsa<title>anda
<taskbody>andoptional<titlealts>,<shortdesc>,<prolog>,and<related-links>.
The<taskbody>elementisthemainbody-levelelementinsideatasktopic.Ataskbodyhasavery specificstructure,with thefollowingelementsinthis order:<prereq>,<context>,<steps>,<result,
<example>and<postreq>. Eachofthebodysectionsisoptional.
<prereq>
Describesinformationneededbeforestartingthecurrenttask.
<context>
Providesbackgroundinformationforthetask.Thisinformationhelpstheuserunderstandwhat thepurposeofthetaskisandwhattheywillgainbycompletingthetask.Thissection shouldbe briefand doesnotreplace orrecreateaconcepttopiconthesamesubject,althoughthecontext sectionmayincludesomeconceptualinformation.
<steps>
Providesthemaincontent ofthetasktopic.Ataskconsistsofa seriesofstepsthataccomplish thetask.The<steps>sectionmust haveoneormore<step>elements,whichprovidethe specificsabouteachstep ininthetask.
The<step>elementrepresentsanactionthata usermust followtoaccomplisha task.Eachstep inataskmust containacommand<cmd>elementwhichdescribes theparticularaction theuser mustdotoaccomplishtheoveralltask.Thestepelementcanalsocontaininformation<info>, substeps<substeps>,tutorialinformation<tutorialinfo>,a stepexample<stepxmp>, choices
<choices>orastepresult<stepresult>,althoughthese areoptional.
<result>
Describestheexpectedoutcomeforthetaskasawhole.
<example>
Providesanexamplethatillustratesorsupportsthetask.
<postreq>
Describesstepsortasks thattheuser shoulddo afterthesuccessfulcompletionof thecurrent task.Itisoftensupportedbylinkstothenexttaskortasks inthe<related-links>section.
Here‘sanexampleofa tasktopic.
<task id="ertx">
<title>Creating an ERTX file</title>
<taskbody>
<context>Each morning before breakfast you need to create a fresh ERTX file.</context>
<steps>
<step><cmd>Start ERTX.</cmd></step></steps>
<step><cmd>Click New ERTX File.</cmd></step></steps>
Chapter3.DITAmarkup 11
</steps>
<result>You now have your ERTX file for today!</result>
</taskbody>
</task>
Modules
task.mod (DTD)
taskMod.xsd,taskGrp.xsd (Schema)
Reference
Referencetopics describeregularfeaturesof asubjectorproduct,suchascommandsinaprogramming language.
Whyreference?
Intechnicalinformation,referencetopics areoftenusedtocoversubjectssuchasthecommandsina programminglanguage.Referencetopics canholdanythingthathasregularcontent,suchasingredients forfoodrecipes,bibliographic lists,catalogues,and thelike.Referencetopicsprovidequickaccessto facts.Informationneededfordeeperunderstandingof areferencetopicorto performrelatedprocedures shouldbeprovidedina conceptortasktopic.
Referencestructure
The<reference>elementdefinesatop-levelcontainerforareference topic.Referencetopicshavethe samehigh-levelstructureastheothercoreDITAtopic types,witha title,shortdescription, andbody.
Withinthebody,referencetopicsorganize contentintooneormoresections, propertylists,ortables.
The<refbody>elementholdsthemaincontentofthereferencetopic.Referencetopics limitthebody structuretotables(bothsimpleandstandard),propertylists,syntax sections,andgenericsectionsand examples.
Alloftheelementsof<refbody>areoptionaland mayappearinanysequenceandnumber.
<section>
Representsanorganizationaldivisioninareference topic.Sectionsorganize subsetsof
informationwithina largertopic.Youcanonlyincludea simplelistofpeer sectionsina topic;
sectionscannotbenested.Asectionmayhaveanoptionaltitle.
<refsyn>
Containssyntaxorsignaturecontent (forexample,a command-lineutility’scallingsyntax,oran API’ssignature).The<refsyn>containsa brief,possiblydiagrammatic descriptionof thesubject’s interfaceorhigh-levelstructure.
<example>
Providescontainingexamples thatillustrateor supportthecurrenttopic.The<example> element hasthesamecontentmodelas<section>.
<table>
Organizesinformationaccordingintoa tabularrowsandcolumnsstructure. Tablemarkupalso allowsformorecomplexstructures, includingspanningrowsandcolumns,aswellastable captions.
<simpletable>
Holdsinformationinregularrowsandcolumnsand doesnotallowfora caption.
<properties>
Listspropertiesand theirtypes,values,anddescriptions.
Here‘sanexampleofa referencetopic.
<reference id = "boldproperty">
<title>Bold property</title>
<shortdesc>(Read-write) Whether to use a bold font for the specified text string.</shortdesc>
<refbody>
<refsyn>
<synph>
<var>object</var><delim>.</delim><kwd>Font</kwd><delim>.</delim>
<proptype>Data type</proptype>
<propvalue>Boolean</propvalue>
</property>
<property>
<proptype>Legal values</proptype>
referenceMod.xsd, referenceGrp.xsd(Schema)
Domains
ADITAdomaindefinesaset ofelementsassociatedwitha particularsubjectareaorauthoring requirementregardlessoftopictype.
Theelementsinadomainare definedina domainmodulewhichcanbeintegratedwith atopictypeto makethedomainelementsavailablewithin thetopictype structure.Currentlythefollowingdomains are provided:
Table1.DITAdomains
Domain Description Shortname Modulename
Typographic Forhighlightingwhentheappropriate semanticelementdoesn’texistyet
Software Fordescribingsoftware sw-d softwareDomain.mod (DTD)
softwareDomain.xsd (Schema) Userinterfaces Fordescribinguserinterfaces ui-d uiDomain.mod (DTD)
uiDomain.xsd (Schema) Utilities Forprovidingimagemapsandother
usefulstructures
ut-d utilitiesDomain.mod (DTD) utilitiesDomain.xsd (Schema)
DITA maps
Mapsorganizetopicsforoutputtoa specificdeliverable,includinggeneratingnavigationfilesandlinks torelatedtopics.
Chapter3.DITAmarkup 13
What are maps?
DITAmapsare documentsthatcollectandorganize referencestoDITAtopicstoindicatetherelationships amongthetopics. Theycanalsoserveasoutlinesortablesof contentsforDITAdeliverablesandasbuild manifestsforDITAprojects.
DITAmapsrepresentthearchitectureofaninformationset –whattopicsareneeded, inwhatorderor relationships,tosupporta particularsetofuser goalsorotherrequirements.
Mapsdescribethecontextinwhichthetopics willbe read– theaudience, platform,relationships,
requirementsof theinformationset.Inthisway, thetopicsthemselvesbecomerelatively context-free,and canbemoreeasilyusedandreused inmanydifferentcontexts, asdefinedbymaps.
Mapsdrawonarichsetofexistingbestpracticesandstandards fordefininginformationmodels, suchas hierarchicaltaskanalysis.They alsosupportthedefinitionofnon-hierarchicalrelationships,suchas matricesandgroups,whichprovidea setofcapabilitiesthathassomesimilaritiestoRDFand ISOtopic maps.
AmapfilereferencesoneormoreDITAtopicfilesusing<topicref>elements.The<topicref>elements
AmapfilereferencesoneormoreDITAtopicfilesusing<topicref>elements.The<topicref>elements