DITA's features include: 13 |
18 |
19 |Information typing is also used in other methodologies such as
20 |
Modularity is the technique of building large complex things in smaller, 16 | self-contained pieces. Modular furniture is a good example of modularity in 17 | practice. Instead of being one large piece, a modular couch may be four pieces 18 | that can be arranged in different ways to form different couch configurations. 19 |
20 |Creation of a manual can also be
21 |
XML technologies (such as
31 |
DITA can be described as an approach to information architecture. That's 16 | why there's an A for Architecture in DITA! 17 |
18 |A great definition of architecture in the DITA context can be found in
19 | the book
20 | DITA 101:
21 |
This definition is great because it highlights the facts that: 27 |
All DITA elements have a
14 |
All DITA based processors use the
23 |
Just as they provided a good definition of what architecture means in 14 | the DITA context, 15 | Rockley, Manning et al follow up with a lovely, succinct 16 | definition of DITA. 17 |
18 |The features and capabilities of content referencing was extended in
7 | DITA 1.2, making it possible to conref multiple elements at the one time, to
8 | indirectly reference content, and to
9 |
Re-use of content is easier for the author to accomplish if the elements
9 | to be re-used are carefully
10 |
To best take advantage of content re-use, you should adopt practices to 8 | reduce the impediments, increase the opportunities for re-use, and to make the 9 | process of re-using easier. 10 |
11 |There is a danger in including links (
The solution to this problem in DITA is map-based linking. Links can be
15 | automatically generated at the bottom of each topic, with the links based on
16 | either the structure of the hierarchy of
17 |
An old OASIS News story from 2002, titled
7 | The Holy Grail of Content Reuse: IBM's DITA XML,
8 |
DITA design focuses upon the "topic" as a conceptual unit of 14 | authoring. Larger documents can be created by aggregating topic units. A 15 | "content referencing" (conref) mechanism may be used at the mark-up level to 16 | combine several topics into a single document, or to share content among 17 | topics. 18 |
19 |The DITA design has a unified content reuse mechanism by which an 20 | element can replace itself with the content of a like element elsewhere, either 21 | in the current topic or in a separate topic that shares the same content 22 | models. The distinction between reusable content and reusing content, which is 23 | enshrined in the file entity scheme, disappears: Any element with an ID, in any 24 | DITA topic, is reusable by conref. 25 |
26 |DITA's conref 'transclusion' mechanism is similar to the SGML conref 27 | mechanism, which uses an empty element as a reference to a complete element 28 | elsewhere. However, DITA requires that at least a minimal content model for the 29 | referencing element be present, and performs checks during processing to ensure 30 | that the replacement element is valid in its new context. This mechanism goes 31 | beyond standard XInclude, in that content can be incorporated only when it is 32 | equivalent: If there is a mismatch between the reusing and reused element 33 | types, the conref is not resolved. It also goes beyond standard entity reuse, 34 | in that it allows the reused content to be in a valid XML file with a DTD. The 35 | net result is that reused content gets validated at authoring time, rather than 36 | at reuse time, catching problems at their source. 37 |
38 |The
15 |
Including child elements in titles therefore reduces the opportunities 26 | for re-use, increases the risk of a transformation error caused by 27 | mis-interpretation of the mark-up, and complicates what should be a simple 28 | semantic element. 29 |
30 |However, it
31 | is technically possible to embed
32 |
10 |
11 |If a topic being referenced in an
21 |
If you want a cross-referenced Web or external
28 | resource to open in a new window, code the
29 |
The
17 |
When writing a task topic, you will often include a pre-requisites
21 | (
Rather than including a link to an associated topic in an
27 |
The
16 |
When used in conjunction with a
23 |
31 |
Do not include any unlinked text in the related links
10 |
14 |
Answering a question about whether additional text is allowed within
23 | the
24 |
Having text like that plays havoc with localization anyway, so it 30 | was just too much trouble to even try. 31 |
32 |Go with relationship tables. Remember that you can use multiple 33 | relationship tables, if that makes them easier for you to work with. 34 |
35 |Use descriptive folder and file names. Use
19 |
If you need to create Microsoft Visual Studio Help 2 output, the best 7 | approach is to create an HTML Help (.chm) file through the DITA Open Toolkit 8 | normally, and then use a tool such as HelpWare FAR to convert the .chm file to 9 | .hxs format. 10 |
11 |13 |
14 |Referring to the US Government's
18 |
23 |
43 |
The process of creating, producing and delivering a document in DITA's 15 | modular, structured authoring environment can be divided into three different 16 | stages: 17 |
When a team of authors is working on the same collection of topics,
18 | particularly when the collection is very large, it is sometimes difficult to
19 | identify a problem with the build. For example, a topic referenced in the
20 |
Some information architects provide each author with a ditamap of that 24 | author's topics. Before the author submits the final set of topics, the ditamap 25 | must successfully and cleanly build as a unit. The author's ditamap can be 26 | discarded after testing if it is not otherwise used for publishing. 27 |
28 |This unit testing approach allows any issues to be addressed in a 29 | smaller, quicker to build, environment. 30 |
31 |
10 |
http://wiki.oasis-open.org/dita/SyntaxDiagram 23 |
24 |Image maps can be defined in DITA, but rather than being content, image maps contain presentational information. (In theory, DITA should only contain content, and not any presentational form information.)
Make sure you SVG editor is fully W3C SVG compliant. You will have fewer problems in Inkscape (an open source dedicated SVG editor) than you might have in a commercial tool such as Illustrator. Microsoft Visio also seems to provide compliant SVG output.
You should also try to draw your images in the size in which you wish to render the in the output.
Refer to http://www.thecontentwrangler.com/article/do_screen_captures_still_makes_sense/
Summary:
If you find that you are deliberately coding your DITA topics in such a 14 | way as to achieve a particular output effect, you are without doubt taking the 15 | wrong path. DITA topics must be delivery-agnostic; they must be free of as much 16 | context (how the information is going to be used, presented or sequenced) as 17 | possible. 18 |
19 |Line breaks are formatting constructs, so in general, DITA mark-up 13 | doesn't provide for them. However, it's not quite so clear cut. Despite working 14 | to the ideal that content should be separated from form, DITA does provide for 15 | a good deal of form mark-up. 16 |
17 |Table column widths can be specified in DITA, even though that's form. 18 | Image sizes can be specified in DITA, and that too is form. 19 |
20 |It is possible to use these loopholes in the separation of content and 21 | form to make possible things such as line breaks in titles. For example, a 22 | workaround is to place a one pixel by one pixel image within the title, and set 23 | the image element's placement attribute to break. This will cause, in most 24 | outputs, the title to be displayed with text before the image displayed on a 25 | different line to text following. 26 |
27 |You must avoid the temptation to use such workarounds 28 | in an attempt to introduce form into DITA content. 29 |
30 |Avoid including transitional text in topics. 10 |
11 |Transitional text is text that leads the reader to a following topic, or
12 | connects the topic to a previous topic. Examples of transitional text include:
13 | As we saw previously...
and
14 | This processed is explained later...
. In DITA, topics should be
15 | designed to be context-agnostic, so that a topic can be re-used in different
16 | publications or outputs, in different sequences. Transitional text reduces
17 | re-use opportunities.
18 |
20 |
A feature of some document delivery formats, notably Eclipse Help, is
16 | the
17 |
Change the examples in this group of topics to
19 |
DITA includes a range of elements and attributes to manage references in 8 | ditamaps, and to govern the way the references are treated during the 9 | publishing process. 10 |
11 |When a ditamap is
18 |
The hierarchy of topic references in the ditamap controls not only the 19 | sequence of topics in the output and/or the TOC, but also influences 20 | automatically-generated navigation links and generated summary content in 21 | parent topics in some output formats. 22 |
23 |DITA permits you to adjust the basis on which the automatic navigation
24 | links are generated through the
25 |
Which collection type to use is dependent on the nature of the content. 29 | However, if in doubt, leave the default, which provides links to any child 30 | topics, and a link back from child to parent. This ensures that all topics in a 31 | hypertext output such as HTML can be traversed using links alone. 32 |
33 |By default, the link text used for generated links will be the title of 19 | the target topic. 20 |
21 |If you want the link generated by a reltable to have a different title
22 | to the title of the linked topic itself, you may think the technique would be
23 | to use a
24 |
The technique to use is to add a
28 |
One of the most powerful features of DITA is the automatic generation of 19 | cross-reference links in the output. This feature allows greater content 20 | re-use, as it removes linking context from topics and moves it to the map. 21 |
22 |Cross-reference links at the bottom of output topics are generated by
23 | hierarchical relationships defined in the ditamap, non-hierarchical
24 | relationships defined in the
25 |
Of course, how links are generated will ultimately be up to the 29 | publishing engine you use. 30 |
31 |The
32 |
You should not nest bookmaps within ditamaps, as the 14 | structure will cause confusion for both processing software and for 15 | documentation authors. 16 |
17 |If you need to re-use content from a bookmap inside a 18 | ditamap, then a lower-level ditamap should be nested in the bookmap, and that 19 | lower level ditamap re-used in the main ditamap. In fact, except for small 20 | documents, you should aim to have the top-level bookmap contain only map 21 | references, and no topic references. 22 |
23 |In DITA, each topic is written as a standalone chunk of content. The 15 | style in which a topic title, for example, is eventually presented to the user 16 | is determined by the position of the topic in the relevant ditamap. 17 |
18 |For example, if a topic called
19 | About SD Cards
is located at:
20 |
If that same topic is re-used in a different ditamap, located at:
24 |
And it gets better! Topic titles can be different in different ditamaps. 29 | 30 |
31 |
52 |
Topics to be included in the output are referenced through
16 |
Simplistically, any topic referenced in the ditamap will be included in
30 | the output. An exception is for topics with the
31 |
If a topic is to be included in the output file (eg, a CHM file) it must be nominated in the ditamap. The ditamap is used as the basis for the Table of Contents in many output types. To exclude a topic from the output table of contents, the relevant ditamap topicref must have its
10 |
Topic-level content reuse is simple to understand. 9 |
10 |A ditamap is an ingredient list of a collection. More than one ditamap 11 | can reference the same topic. 12 |
13 |So if you have a repository of DITA content topics covering how to use a 14 | range of cameras from the same manufacturer, we could create a ditamap for the 15 | Model 400 User Guide, another ditamap for the 16 | Model 700 User Guide, and another for the 17 | Model 700 Administrator's Guide. Some topics might be common 18 | to all ditamaps, while others might be unique to one. 19 |
20 |
10 |
http://dita.xml.org/improving-relationships-relationship-tables 25 |
26 |When using filtering in single-sourcing, you must be careful to ensure 16 | that a conditional processing rule doesn't result in invalid DITA. Filtering 17 | must not result in a required element being removed during processing. 18 |
19 |For example, in the following snippet, if a condition of
20 | exclude web_only and exclude print_only
was set, there would be no
21 | steps in the task, and the topic would be invalid. (The
22 |
The
16 |
To extend the functionality of the
23 | Market
and
30 | Publication
.
31 |
Although you should avoid the use of composite topics in any case, there 18 | are some complications when filtering such content. 19 |
20 |If you have a ditamap
21 |
Even if the chunking feature is used to split the composite DITA topic 29 | into multiple HTML topics, for example, the entire contents of the DITA topic 30 | will be output unless condition attributes are applied within the topic. 31 |
32 |It is possible in DITA, and often good practice, to have nested
21 | ditamaps. Although it does depend on circumstance, it is generally better
22 | practice to apply conditions to the
23 |
The reason for this, and a point that should always be considered when 28 | deciding on a filtering strategy, is the reduced processing load during 29 | generation of the output. If the processor has to read in a topic, or a nested 30 | map, only to find it's not needed in the current build because of the filtering 31 | metadata, it is an inefficient model. It is much better for the exclusion to be 32 | notified to the processor before having to load the file. 33 |
34 |seeand 8 |
see-alsoredirection. Index entries can be applied in the ditamap, 9 | in the topic prolog, and inline within the topic content. 10 |
The indexing features in DITA are built around three elements:
16 |
When working in a topic-based, modular architecture, where metadata
13 | plays a key role, one of the major challenges for authors is managing metadata.
14 | In this respect,
15 | managing metadata
means such things as ensuring consistent
16 | metadata use, using metadata for retrieval of authoring topics, enforcing
17 | business metadata rules, and effective use of conditional metadata attributes.
18 | The most effective way of managing metadata is through a
19 |
If a
22 |
There are some DITA software tools that provide some features that
27 | leverage metadata, such as reporting on attribute values in a collection. You
28 | may find these tools useful in supplementing your authoring tool features. Two
29 | such tools are
30 |
7 |
I'd suggest that our approach to style policies should consist of 16 | selectors and properties. In essence, a policy file should be able to attach 17 | any style or layout property (including an exclude or hide property) to any 18 | content fragment. The selectors should be CSS-like matches on inherited class, 19 | instance identifier, token value, or nesting of the above. The goal should be 20 | to put policy decisions in the hands of the broad audience that wouldn't be 21 | successful with XSLT. (Because XSLT is always available as a general fallback, 22 | style policies can provide a purely declarative set of selectors and properties 23 | rather than executable flow and expressions.) To produce books from bookmaps, 24 | the set of properties will need properties like page break and so on. A bit 25 | more on the thought: 26 | http://www.oasis-open.org/apps/org/workgroup/dita/email/archives/200409/msg00022.html 27 |
28 |Paul's note below highlights the convergence of this approach with 29 | DITA conditional values, which also provide a system of selectors and 30 | properties. In a perfect world, existing DITA values files would remain valid 31 | instances of the more general style policies format. A transform might be 32 | acceptable. 33 |
34 |The
21 |
Do not use this attribute when authoring DITA topics 31 | or maps. 32 |
33 |The
21 |
For example, if a topic was based on figures published in a Department
31 | of Transport report, the source element may be coded as:
32 |
When published to an HTML-based output format, the address in the
37 |
Most DITA content elements include the
18 |
Valid values for the
26 |
Some authoring tools may highlight topics with different
39 |
Body elements are the most common content authoring block elements, and 17 | include: 18 |
19 |A choice list is a special purpose list used within
16 |
The choice list (
An example of a choice list being used within a step is:
25 |
Examples of programming, scripting, or mark-up language code are marked
17 | up using the code phrase (
Code block elements can be nested inside a paragraph (or other block 24 | element). 25 |
26 |If you have text that introduces the codeblock and more text that
27 | immediately explains the code, you can use a structure such as in the following
28 | example:
29 |
Line breaks can be used inside
40 |
Some information structures, particularly terms with corresponding 15 | definitions, can be marked up as either definition lists or tables. 16 |
17 |If the content is indeed made up of terms and
18 | definitions, the definition list (
Definition lists are particularly suited to defining or explaining 25 | components or items. 26 |
27 |Definition lists are rendered with fewer potential complications than 37 | tables, and are semantically stronger than the more generic table structure. 38 |
39 |A footnote is usually seen as being specific to page layout output 16 | formats, so marking up text as a footnote could be viewed as recording 17 | presentational information within content; something that DITA tries to avoid. 18 |
19 |However, footnotes can also be considered as semantic identifiers for 20 | supplementary information that doesn't belong inline in the text. The footnote 21 | content is not critical to understanding the content, but provides extra 22 | information that may be useful to some readers. 23 |
24 |The footnote (
An example of a footnote (
39 |
40 |Images can be used to support documentation of task steps, as
17 |
The base DITA elements are grouped into
17 |
The DITA element mark-up domains are: 23 |
Different sets of elements are intended for use when documenting 39 | different types of things. The software domain, for example, contains the 40 | elements designed to semantically describe software characteristics. 41 |
42 |The element domains are technically
43 |
The map elements are a small set of elements, some of which have been
15 |
The map elements include: 20 |
There are a number of concepts and principles of XML mark-up in general, 8 | and DITA mark-up in particular. 9 |
10 |The intention of the DITA approach is that the elements most commonly 17 | cross-referenced, such as topics, sections, figures and tables, should have a 18 | title. In some cases, the title element is mandatory. 19 |
20 |Even though the DITA DTD may technically allow 21 | multiple titles to exist in one section, you should limit your section content 22 | to one title. Do not use titles as though they are headings. If you need 23 | multiple headings in a section, chances are that you really need multiple 24 | sections. 25 |
26 |The metadata domain elements are designed for describing index entries 11 | and map-level metadata elements. 12 |
13 |Parameter lists are a special purpose list used to describe parameters
18 | in a program or application programming interface. The parameter list
19 | (
A parameter list (
An example of a parameter list being used to explain some programming code is:
28 |
The
21 |
A processor will treat line-end characters within a
29 |
The
33 |
The DITA programming domain is a set of mark-up elements used for 17 | documenting programming languages and their use. The software domain is a 18 | similar set of elements used for documenting software applications. 19 |
20 |To identify a program or script name within an
21 | end-user's use of a software application, you should use the
22 |
To identify a function, API or sub-routine within
26 | documentation aimed at programmers, you should use the
27 |
The elements in the programming domain are designed for documenting 12 | programming languages. 13 |
14 |The DITA prolog elements contain the main metadata for a topic or 14 | collection. 15 |
16 |The types of information recorded in the prolog include: 17 |
The
17 |
During processing to a reading format, steps with an
28 | Optional:
or
30 | Required:
prefix.
31 |
A single step procedure should still be marked up
14 | using the
15 |
Some writers object to the default processing of something like: 20 |
21 |as 25 |
26 |because they feel the number is unwarranted or confusing. 28 |
29 |However, the semantics of the DITA source should always be observed over
30 | any preference in output format. The output processing should be changed if the
31 | output needs to be different (in our case, represented as a bulleted item
32 | instead of a numbered item). The DITA source shouldn't be corrupted or
33 | bent
to achieve a certain output result.
34 |
The software domain elements are designed for documenting the operation 11 | of a software program. 12 |
13 |Special characters and dates require different handling than normal 8 | text. 9 |
10 |The system output (
The
27 |
Example:
32 |
The topic elements are the main structural elements of topics. Some
15 | topic elements are generic (ie, inherited from the
16 |
Examples of topic elements include: 20 |
The two types of general purpose tables in base DITA are: 19 |
List of Tablesgenerated during the publishing process. 28 |
Both types of table are based on the CALS standard table structure; the 42 | table structure of HTML is based on the same standard. 43 |
44 |DITA also includes some special purpose tables, including relationship
45 | tables (used in ditamaps for cross-reference metadata) and
46 |
The elements in the typographic domain are used to describe styling
11 | characteristics. They are primarily intended as the basis for
12 |
Semantic elements should always be used in preference 17 | to typographic elements. 18 |
19 |All DITA elements have a
22 |
All DITA based processors use the class attribute to determine how an
31 | element should be processed, rather than by using the element name itself. This
32 | is because
33 |
The user interface domain elements are designed for documenting the user 12 | interface of a software program. 13 |
14 |The utilities domain elements are non-semantic elements used in defining 12 | image maps. 13 |
14 |In XML document mark-up languages, including DITA and XHTML, there are 17 | typically two types of content mark-up elements: block (or paragraph) elements, 18 | and phrase (or inline) elements. 19 |
20 |Phrases are spans of text within a larger block of text, such as words
21 | within a paragraph. Typical phrase elements are term (
Blocks are paragraph-like elements, which are normally displayed with
26 | spacing above and below the block. Typical block elements are paragraph
27 | (
It is possible that an unordered list's items might be re-sequenced (if 7 | not randomised), such as where the unordered list comprises possible answers 8 | for a multiple choice question in a Learning specialisation topic. 9 |
10 |Perhaps discuss that lists can be sorted during processing. Maybe use 11 | linklist and linkpool as examples. 12 |
13 |How should an expansion of acronym, abbreviation or other term be 8 | handled? For example, in the snippet: 9 |
10 |technologies such as XML Localization Interchange File Format 11 | (XLIFF)12 |
should the mark-up be: 14 |
15 |or 17 |
18 |or 20 |
21 |or something else? 23 |
24 |For content to be truly separated from format, structure, context and
20 | delivery, there can be no links embedded within the topic content, because
21 | links contain
22 |
Embedded links create a dependency upon the linked topics; the topic can 25 | only make sense if the target topics for each of the links it are delivered 26 | alongside it. If a target topic is not included in the same collection as the 27 | topic, then the link will be broken. 28 |
29 |DITA includes automatic linking mechanisms based on relationships
30 | established in
31 |
Concept topics are used to document conceptual or overview information. 15 | They contain background information that users must know before they can successfully 16 | work with a product or within a process. Concepts can be broken into sections, but they 17 | are primarily comprised of simple paragraphs and unordered lists.
18 |Concept topics answer the question what is?
.
The root element of a concept topic is
20 |
ABS
may stand for
17 | Anti-lock Braking System
or for
18 | Automatic Brightness Sequencer
. A disambiguation topic is
19 | typically a single topic explaining the different uses of the term, and links
20 | to the relevant alternative topics.
21 |
Reference topics are used to describe features of sets of things, such
15 | as codes, types and commands. Information that normally demands tabular presentation
16 | probably belongs in reference topics. Catalogues, directories and bibliographies are
17 | good examples of reference topic information. Reference topics are often
Reference topics contains facts without explanation
.
The root element of a reference topic is
22 |
DITA is designed around topic
21 |
A
29 |
A common form of documentation is Application Programming Interface (API) documentation. This involves documenting the functions of a shared programming library, and allows developers to re-use common programming functions. The information structure of an API function may be:
A specialised reference information types should be used for this sort of information structure. Some such specialised information types are available publicly, and are suited for particular programming languages. For example, the is a Java API information type available from the DITA Open Toolkit area on SourceForge.
Task topics are used to document the steps of a particular task or procedure, 14 | or to document the stages within a high level process. Task topics are the building 15 | blocks for task-oriented documentation. Task topics are more strictly structured than 16 | concept and reference topics.
17 |Task topics address the question of how to?
.
The root element of a task topic is
19 |
All DITA information types have
21 | evolved
from the
22 |
Apart from for
33 |
The root element of an untyped topic is
42 |
Topics are the building blocks of DITA, and a methodical approach to 11 | topic creation will result in consistent and more effective documents. 12 |
13 |9 |
10 |Another interesting difference is that DITA allows other information
11 | types to be defined through
12 |
8 |
9 |Source: Deborah Pickett, Yahoo! DITA Users Group 27 |
28 |
29 |
Follow up from Michael Priestley 33 |
34 |
7 |
A simple example topic content model for describing a software feature 11 | might be: 12 |
13 |To create a new topic type (something other than topic, task, concept or reference), the steps that Eliot Kimber suggests you should follow are:
7 |
Mike Kokic, correspondence to dita-users Yahoo group 32 |
33 |Link to Task Topic Exemplar in Exegesis
Source: Hughes (2009)
ditamap is not a term; it is just a normal word. The exception is when 10 | it is being defined. Avoid starting a sentence with ditamap. 11 |
12 |conref is not a term; it is just a normal word. The exception is when it 13 | is being defined. Avoid starting a sentence with conref. 14 |
15 |
15 |
John Durham Peters quotation from keynote address delivered at ANZCA 14 | 2010, Canberra, Australia. 15 |
16 |A footnote must exist in a paragraph, as it is an inline element, not a 11 | block element. 12 |
13 |