OASIS Darwin Information Typing Architecture (DITA) TC

Per today's TC call, I'm providing a
minimal rewrite of the "What are topics?" topic in the architectural
spec. Here's the text of the topic, with updates in italics (a change to
the shortdesc, and a new third paragraph):

>>>>
What are topics?
-------------------------
A topic is a unit of information with
a title and some form of content, short enough to be specific to
a single subject or answer a single question, but long enough to make sense
on its own and be authored as a unit.

In DITA, a topic is the basic unit of
authoring and of reuse. A document may contain one topic or multiple topics,
and a document type may support authoring one or many kinds of topics.
But regardless of where they occur, all topics have the same basic structure
and capabilities. Books, PDF files, Websites, and help sets, for example,
can all be constructed from the same set of underlying topic content, although
there may be some topics that are unique to a particular deliverable, and
the organization of topics may differ to take advantage of the unique capabilities
of each delivery mechanism.

DITA topics can be as small as a
title that organizes other subtopics or links, or as large as a few pages
or screens of content. Larger units of content, such as complex reference
documents or book chapters, can be created by nesting topics, either directly
in a single document, or indirectly through references in a DITA map. Nested
DITA topics can be used to accomodate the migration of legacy non-topic-oriented
content, as well as information with specific authoring requirements, such
as marketing material or API reference documents.

Reference information is inherently
topic-oriented, since it requires information to be modular and self-contained
for the sake of retrievability.

Topic-oriented authoring for conceptual
and task information has its roots in Minimalism, an instructional design
technique first espoused by John Carroll. The minimalist approach to information
design focusses on identifying the smallest amount of instruction that
allows for the successful completion of a task, or that provides basic
knowledge of a concept. Readers have goals, and they want to achieve those
goals as quickly as possible. Generally, readers don't want to read information
just for the pleasure of reading. They are reading to learn or to do something.

Some of the key principles of Minimalism
are: 

 - Support actions. Let people
act as they learn, and let them pursue the goals they want to accomplish.

 - Document tasks, not tools or
functions. 
 - Help readers anticipate and
avoid errors. 
 - Let readers explore. They don't
need explained what they can discover for themselves. 

While DITA's topic-oriented approach
has its roots in instructional design, the topic-based approach can be
useful for any information that has human readers and a consistent structure.
>>>>

Michael Priestley

IBM DITA Architect and Classification Schema PDT Lead

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25

accomodate -> accommodate.



  

  

  From: Michael Priestley 
  [mailto:mpriestl@ca.ibm.com]
Sent: Tuesday, 2007 January 02 
  22:11
To: dita@lists.oasis-open.org
Subject: [dita] 
  suggested update to topic "What are topics?"


  

Per today's TC call, I'm providing 
  a minimal rewrite of the "What are topics?" topic in the architectural spec. 
  Here's the text of the topic, with updates in italics (a change to the 
  shortdesc, and a new third paragraph):

>>>>
What are 
  topics?
-------------------------
A 
  topic is a unit of information with a title and some form of content, 
  short enough to be specific to a single subject or answer a single question, 
  but long enough to make sense on its own and be authored as a unit.

In DITA, a topic is the basic unit of 
  authoring and of reuse. A document may contain one topic or multiple topics, 
  and a document type may support authoring one or many kinds of topics. But 
  regardless of where they occur, all topics have the same basic structure and 
  capabilities. Books, PDF files, Websites, and help sets, for example, can all 
  be constructed from the same set of underlying topic content, although there 
  may be some topics that are unique to a particular deliverable, and the 
  organization of topics may differ to take advantage of the unique capabilities 
  of each delivery mechanism.

DITA topics can be as small as a title that organizes other 
  subtopics or links, or as large as a few pages or screens of content. Larger 
  units of content, such as complex reference documents or book chapters, can be 
  created by nesting topics, either directly in a single document, or indirectly 
  through references in a DITA map. Nested DITA topics can be used to accomodate 
  the migration of legacy non-topic-oriented content, as well as information 
  with specific authoring requirements, such as marketing material or API 
  reference documents.

Reference 
  information is inherently topic-oriented, since it requires information to be 
  modular and self-contained for the sake of retrievability.

Topic-oriented authoring for conceptual 
  and task information has its roots in Minimalism, an instructional design 
  technique first espoused by John Carroll. The minimalist approach to 
  information design focusses on identifying the smallest amount of instruction 
  that allows for the successful completion of a task, or that provides basic 
  knowledge of a concept. Readers have goals, and they want to achieve those 
  goals as quickly as possible. Generally, readers don't want to read 
  information just for the pleasure of reading. They are reading to learn or to 
  do something.

Some of the key 
  principles of Minimalism are: 

 - Support actions. Let people act as they learn, and let them 
  pursue the goals they want to accomplish. 
 - Document tasks, not tools or functions. 
 - Help readers anticipate and avoid errors. 
  
 - Let readers explore. They 
  don't need explained what they can discover for themselves. 
  

While DITA's topic-oriented 
  approach has its roots in instructional design, the topic-based approach can 
  be useful for any information that has human readers and a consistent 
  structure.
>>>>

Michael Priestley
IBM DITA Architect 
  and Classification Schema PDT 
  Lead
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25