Michael,
Sounds very good. I suggest removing the
commas that I marked in red below.
JoAnn
JoAnn T. Hackos, PhD
President
Comtech Services, Inc.
710 Kipling Street, Suite 400
Denver, CO 80215
303-232-7586
joann.hackos@comtech-serv.com
joannhackos Skype
www.comtech-serv.com
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 link,
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 accommodate
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