DITA XML

In a topic-oriented architecture such as DITA, content is authored in small, independent units that are assembled to provide help systems, books, courses, and other deliverables. Each unit of information answers a single question for a specific purpose. That is, each topic has specific, independent subject matter

Because each topic has a specific meaning, DITA topics are tailor-made for semantic processing. However, current semantic processors can't read the text of a topic to find out what it means. What's missing is a formal declaration of the topic's subject matter that a semantic processor can understand

Simple Knowledge Organization System (SKOS) provides a standard for indicating the subject matter of content. SKOS lets you define the subjects for a particular subject matter area (organizing these subjects as a taxonomy if desired) and then classify each piece of content to indicate its subject. For instance, using SKOS, you could define configuration and security as subjects, and classify the three example topics that relate to those subjects so that users could browse the subjects to find the content regardless of whether the words "configuration" or "security" actually appear in the text.

This is where constraints in the upcoming DITA 1.2 spec comes to the rescue, as it provides a means to specialize without specialization, not by creating new elements, but by constraining your usage of DITA elements to those you actually use. This results in a writing team needing less than the full standard, usefully constraining what tags a writer can use in order have them better focus on the job that they are supposed to do. His take on using them was to start with the most constrained condition, and then loosen the constraints as required as needs evolve.

Keys provide a way for authors to create addresses to resources through the use of a named identifier rather thanto a specific URI pointer. In other words, I can create an easy-to-remember key, like “ms-word-functions” that actually resolves to a URL “http://support.microsoft.com/kb/211982” and link to this URL using the key name in my DITA topic.

Any time a topic makes use of a key reference, that topic is explicitly binding itself to a map (or many maps), meaning that a topic is no longer a unit of information that is completely independent of any particular context in which it is assembled into. You could make the argument that any reference defined in a topic to an external resource (e.g., an image or a cross-reference to another topic) by definition creates a dependency on that topic. And arguably, the referenced (the endpoint) resource is unaware of the object that is referencing it, regardless of whether it's a topic reference or a cross-reference. But there is an additional dependency in the case of keys: Any map that references a topic with a key reference must define the key. So in a sense, not only does the map (or an ancestor map) need to know about the topic, it needs to discover what the topic is about, specifically related to any key references it points to. Consequently, somewhere along the line, at least one map must define the keys used by a topic.  Did you get all that?  Imagine what your XML authoring tools, CMS systems, and rendering platforms will need to do to manage this.

there are potential downsides too.  Keys and key references add another layer of complexity to planning the authoring, deployment and management of DITA content.  

is not about less content, it is about the reader spending less time on the content.

A task is something a user has to do, a goal they want to attain. A procedure is a set of instructions for manipulating a machine. Manipulating the machine is never the user’s goal in itself. Manipulating the machine may be one of the things the user has to do to accomplish their task, but it is not the task itself. A procedure, therefore, may be part of a task topic, but it is not a task topic in itself.

This is what topic-based writing and task topic types should be about, therefore: creating topics that function for the user by consistently and reliably enabling them to accomplish the whole of their real-world tasks. This is about a great deal more than procedures, and there is a great deal more at stake than reuse.

If a help ID should provide a list of related topics, those topics are shown as separate <relcell> entries in the corresponding <relrow>:

<relrow id=”h4444444″>

This encoding approach takes care of the DITA source side of the context-sensitive help. You’ll need to build a DITA Open Toolkit plugin that processes the relationship table and creates the appropriate mapping files.

What is a content strategy? A content strategy reveals who the end users are, the goals they are pursuing and what tasks they must do to reach the goals. The content strategy explicitly describes what type of information end users need to do the tasks, which gives us the content to include and not include in a manual and how to organize it to make content searchable. A content strategy shall answer a number of questions (for example, open the document via link "information design questions" On http://www.sesam-info.net/planning.htm). The answers are sometimes referred to as the information model.

The content strategy shall also deal with areas such as metadata, reuse strategy, creation and release processes, publishing mechanisms, content ownership and responsibility, tools etc.

Let us elaborate two types of content creation organizations within the technical communication domain: Explicit and implicit organizations.  In the implicit organization there are no content strategy written down. Each member (technical writer, SME etc) has their own view on what content they believe end users need. In the best of worlds these views are aligned without the members having discussed it. In other implicit organizations an information designer has taken the role to plan and design the content (together with the team or not). But the strategy and principle that the information designer is following may not be communicated or understood by the technical writers or SMEs. So the information designer has to be consulted every time a new manual is developed or a macro content change is proposed in an existing manual. In explicit organizations the strategy and principles are written down and communicated.

Good metadata conforms to community standards in a way that is appropriate to the materials in the collection, users of the collection

Good metadata supports interoperability

Good metadata uses authority control and content standards to describe objects

The linkage between a metadata record and the resource it describes may take one of two forms: elements may be contained in a record separate from the item, as in the case of the library's catalog record; or the metadata may be embedded in the resource itself.

The Dublin Core metadata standard is a simple yet effective element set for describing a wide range of networked resources. The Dublin Core standard includes two levels: Simple and Qualified. Simple Dublin Core comprises fifteen elements; Qualified Dublin Core includes three additional elements (Audience, Provenance and RightsHolder), as well as a group of element refinements (also called qualifiers) that refine the semantics of the elements in ways that may be useful in resource discovery.

Another way to look at Dublin Core is as a "small language for making a particular class of statements about resources". In this language, there are two classes of terms -- elements (nouns) and qualifiers (adjectives) -- which can be arranged into a simple pattern of statements.

Administrative metadata is information intended to facilitate the management of resources. It includes information such as when and how an object was created, who is responsible for controlling access to or archiving the content, what processing activities have been performed in relation to it, and what restrictions on access or use apply.

Technical metadata and preservation metadata are particular types of administrative metadata. Technical metadata describes digital files and includes capture information, format, file size, checksum, sampling frequencies, and similar characteristics.

Structural metadata relates the pieces of a compound object together and/or bundles related objects into a package. For example, if a book is digitized as individual page images, structural metadata can record information concerning the order of files (page numbering) and how they relate to the logical structure of the book (table of contents) is also required.

Terms and conditions of use include the copyright status of the object—whether it is in the public domain or is copyright protected—and any restrictions on use. The user should be informed how to obtain permission for restricted uses and how to cite the material for allowed uses.

Attributes of distributed objects should be expressed using standard controlled terms whenever possible.

Factors to consider include:

Tools to support the use of the vocabulary. Is there an online thesaurus? Can it be incorporated into the collection’s search system? Are there cross-references and related terms?