RE: Please describe value of Information Mapping

["Daniel Ng" <kjng -at- gprotechnologies -dot- com>]

*This message was transferred with a trial version of CommuniGate(r) Pro*
This is real high quality research stuff for everyone on this list. First
class post!

-----Original Message-----
From: Bob Doyle [mailto:bobdoyle -at- skybuilders -dot- com] 
Sent: Wednesday, April 09, 2008 2:23 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Please describe value of Information Mapping

Hi all,

This thread has gotten away from Information Mapping to Minimalism, which
are but two of several very important ideas in technical writing.

Since some of you were interested in the long view of someone who has been
working in the field for decades, I thought I would send you a brief history
of comparable ideas and techniques, all of which are of great significance
for technical writers who want to become "information developers" in the age
of the web.

I am thinking of - modularity, structured writing, information typing,
separation of content from presentation, single-sourcing, topic-based,
task-orientation, minimalism, content reuse, conditional processing,
localization-friendly, multi-channel, component publishing,
object-orientation, inheritance, specialization, and simplified XML for
documentation.

I have studied these because they all are contributors to the new Darwin
Information Typing Architecture or DITA standard for structured writing, as
adopted by Adobe FrameMaker, PTC Arbortext, Justsystems XMetaL and several
other authoring tools.

STC Intercom Magazine for April will be a special issue on DITA, for which I
wrote a survey of DITA Tools -  especially editors and content management
systems. I found I could not understand what DITA was doing without
reviewing all the documentation practices of the past few decades,
especially as docs migrated from print to online. But there was little room
for that in an article on tools.

So here is my view of things, with references at the end to all the books in
my tech comm library. Most of these books are still available on Amazon, for
those of you who like to know the Why behind the How of our day-to-day work.

I would appreciate your corrections or criticisms. I will be posting this as
part of the knowledge base for the OASIS DITA website, where I am a member
of the Editorial Board. (http://dita.xml.org)

It will also be part of a History of DITA for our DITA Users organization,
which now has 550 members from 33 countries. (http://www.ditausers.org)
_________________________________

* Before 1960

*
 The historian of technical communications, R. John
Brockmann<http://www.english.udel.edu/Profiles/brockmann.htm>,
researched efforts to document products going back centuries. He finds that
some of today's hottest new documentation ideas were present in the work of
those creating, documenting, and selling the technology of manufacturing
just after the revolutionary war.

(From Millwrights to Shipwrights to the Twenty-First Century: Explorations
in a History of Technical Communication in the United
States<http://www.amazon.com/Millwrights-Shipwrights-Twenty-First-Century-Co
mmunication/dp/1572730773/>
)

 Today's computers, with their spectacular graphical interfaces, allow us to
present animated visual images, even 3-D models to illustrate complex
machinery. But this is not the work of the everyday tech writer. Flash
animations and computer-aided design (CAD) demand skills more like those
found in a game design team than a lone tech writer and wordsmith.

 Brockmann found that two-dimensional images were a key part of 18th century
technical documents. And modern ideas like modularity were there in the form
of documents, which were as often a set of cards as a book. He also found
that early work was very user-centered and task oriented, and that it took
advantage of knowledge already available to the user.

 It seems that much of the change in today's technical documentation is the
direct influence of the computer, and for some obvious reasons:

   - Theorists of computer documentation thought they were in a new field
   and simply reinvented practices long in use for explaining ordinary
   machines.
   - Software documentation, including online help, had become the
   paradigm for today's tech writers.
   - Since desktop publishing appeared, we rely heavily on the computer
   to assist us in the preparation of our documentation.

 * The 1960's and '70's - Programmed Learning, STOP, QRC, Advance
Organizers, Information Mapping

*
 At Harvard in the 1960's, computers were enlisted to become "teaching
machines" by the behaviorist B.F.Skinner. His ideas of "programmed learning"
still have influences in today's eLearning models. His work required
knowledge to be broken down into chunks.

 Hughes STOP - (Sequential Thematic Organization of
Publications)<http://www.ditausers.org/history/STOPbeginnings.pdf>advocated
a storyboard approach with two-page spreads. A large graphic on
one page, with clear labels, faces the main explanatory text on the opposite
page.

 The U.S. Navy published the Quick Reader Comprehension
(QRC)<http://www.ditausers.org/history/QRC_Proposal_1961.pdf>method in
1961. It explicitly called for modular documentation that could be
reassembled and reused for different purposes, perhaps the first mention of
Reuse.

David Ausubel <http://en.wikipedia.org/wiki/David_Ausubel> first
proposed Advance
Organizers <http://wik.ed.uiuc.edu/index.php/Advance_organizers> in 1960.
They are formal versions of the teacher telling the students what will be
said (then saying it, then telling them what was said - a summary, in the
classic three-step teaching method). Ausubel advocated images and clear
titles and subtitles that revealed the structure in a document.

 In the mid-'60's Robert
Horn<http://www.stanford.edu/%7Erhorn/a/site/HornCV.html>(winner of
the ACM SIGDOC Lifetime Achievement Award for Documentation)
developed Information Mapping <http://www.infomap.com/> techniques and
founded the company by that name. Common "information types" were identified
in dozens of standard document types like user manuals, policy and procedure
manuals, annual reports, etc. Identifying standard information types is at
the heart of DITA (Darwin *Information Typing* Architecture).

 In the late '60's, Charles Goldfarb <http://www.sgmlsource.com/>, Edward
Mosher and Raymond Lorie (whose surname initials were used by Goldfarb to
make up the acronym GML) created IBM's Generalized Markup Language for
documents. In 1974, GML became SGML <http://en.wikipedia.org/wiki/SGML>,
with the help of Yuri Rubinsky
<http://en.wikipedia.org/wiki/Yuri_Rubinsky>and others. SGML was the
standard for many years of structured documents in
the military, aerospace, and large computer companies. It became the basis
of DocBook.
*
*
** * The 1980's - IBM Task Orientation, Desktop Publishing, Macintosh
Documentation Guidelines.

*
 In 1981 a team at IBM led by Fred Bethke called for a new "task
orientation" in computer software documentation. Their report, IBM Improving
usability of publications
(1981)<http://www.ditausers.org/history/BethkeIBMpubGuidelines.pdf>,
contrasted documents that reflected the software systems architecture. They
found that a user had to already understand the software to find the help
they needed. Inexperienced users got lost. Another approach was role-based
documentation. The new idea was task orientation, which deals with the tasks
people commonly perform with computer programs, regardless of their job
titles, and focuses on the information needed to perform the tasks.

 In 1984, the new Apple Macintosh was a revolution in computer user
interfaces and a similar revolution in computer documentation. The user
interface for documents was WYSIWYG (what you see is what you get - when you
print the document). Desktop Publishing was born. The first DTP program,
MacPublisher, was created by Bob Doyle <http://www.bobdoyleblog.com/>, in
the year of the Mac. Aldus (later Adobe) PageMaker followed in 1985. These
tools led technical writers to style their documents and even arrange the
content layout on the page. To this day DTP thinking is the most important
inhibitor of content reuse, mixing presentation with content (mea culpa).

The new Macintosh Documentation Guidelines called for three sections.
A *Learning
*overview with tutorials that introduce new concepts and functions, an
extensive *Using *section that spells out how to accomplish tasks, and a
program *Reference *section. To this day, well written books on computers
(for example those from O'Reilly) have Learning (e.g., Learning PHP), Using
(e.g., Programming PHP), and Definitive Reference volumes.

Note how Learning, Using, and Reference map perfectly onto the three DITA
information types specialized from the basic DITA Topic structure -
*Concept,
Task, and Reference*. And note that the Macintosh "Using" section was
task-oriented, just as IBM was recommending.
 In 1986 R. John Brockmann published Writing Better Computer User
Documentation<http://www.amazon.com/Writing-Better-Computer-User-Documentati
on/dp/0471884723/>.
Brockmann described the changes needed to move from paper docs to online. He
reported on the new task-based approach, which limits information to that
needed to perform a single task, assuming that the user can find general
information elsewhere, or very likely already knows it.

 In 1989 Bob Horn published Mapping
Hypertext<http://www.amazon.com/Mapping-Hypertext-Organization-Generation-Li
ne/dp/0962556505/>,
an extraordinary book with fantastic illustrations - all drawn by Horn
himself - exhibiting the kind of structured writing that Information Mapping
was proposing for all documentation. This is still one of the three most
important books in the history of documentation in general (it's not about
computer docs).

Horn's book described seven information types of a structured document -
classification, concept, principle, procedure, process, structure, and fact.
Horn was inspired by Harvard Psychology Professor George
Miller<http://en.wikipedia.org/wiki/George_Armitage_Miller>'s
famous work on the Magical Number
Seven<http://en.wikipedia.org/wiki/Magical_number_seven>(plus or minus
two) -  the number of things easily learned at one time.

 Learning theorist Dr. Ruth Clark <http://www.clarktraining.com/> would trim
these down to five - concept, principle, procedure, process, and fact - her
information types for Training and eLearning - in her workshops and
book Developing
Technical Training: A Structured Approach for Developing Classroom and
Computer-based Instructional
Materials<http://www.amazon.com/Developing-Technical-Training-Computer-based
-Instructional/dp/0787988464/>
.

 * The 1990's - IBM Minimalism and User-Centered Design

*
 In 1990 MIT Press published the research results of another IBM team led by
John M. Carroll. Carroll's book, The Nurnberg
Funnel<http://www.amazon.com/Nurnberg-Funnel-Instruction-Communication-Infor
mation/dp/0262031639/>introduced
the idea of
*minimalism* in technical writing. It was task orientation carried to an
extreme. Minimalism meant small non-linear chunks readable in any order. It
emphasized reading To Do, not reading To Know or To Learn, a phrase first
introduced by Ginny Reddish. It attacked the standard systems approach to
learning of Gagne and Briggs, with its hierarchical decomposition of
learning objectives, which remains to this day as a standard in learning
systems. And it emphasized handling errors when the user could not
accomplish a task.

 In 1994 JoAnn Hackos published her landmark Managing Your Documentation
Projects <http://www.amazon.com/dp/0471777110/>, revised and
republished as Information
Development: Managing Your Documentation Projects, Portfolio, and
People<http://www.amazon.com/dp/0471777110/>by Wiley in 2006. Fully in
tune with task orientation, Hackos book described
only three information types - concept, procedure, and reference. This
compares to Information Mapping's seven types, Ruth Clark's simplification
to five types, and are essentially the same as Apple Macintosh Documentation
Guidelines three components.

 In the mid '90's, Yuri Rubinsky's team at SoftQuad in Toronto (creators of
one of the first and most popular HTML editors, HoTMetaL, became involved in
the development of a compromise markup language somewhere between the
extraordinarily complex SGML and the popular new HTML (Hypertext Markup
Language) for web pages. HTML was a disaster from the point of structured
reusable component documentation, not least because it combined presentation
markup with structural markup. The new markup language was XML (extensible
Markup Language).

 In November 1995 John Carroll convened a workshop, sponsored by the Society
of Technical Communication (STC), to evaluate Minimalism in the years since
the Nurnberg Funnel. Carroll invited his major colleagues - R. John
Brockmann <http://www.english.udel.edu/Profiles/brockmann.htm>, David
Farkas<http://www.uwtc.washington.edu/nav_people/faculty/187>,
JoAnn Hackos <http://en.wikipedia.org/wiki/JoAnn_Hackos>, Hans van der
Meij<http://users.edte.utwente.nl/meij/>,
Janice C. (Ginny) Reddish <http://www.redish.net/>, and others.

 In another part of Toronto in 1995, an IBM documentation team was
developing a Help system for IBM's new line of Visual Age software. Jamie
Roberts returned from graduate study at Waterloo and attended a
brainstorming session to define some basic information topic types for the
new Visual Age Help. He scribbled "concept, task, and reference" on a napkin
and a new help document architecture was born, to be initially known as
MITA, for Mendel Information Typing Architecture. Since MITA was not an
original acronym, IBM switched to Darwin and DITA, which still indicated the
object orientation of the new architecture, with its "inheritance" of topic
structures. There is not much unusual about a Help system that is task-based
and assembled from topics. What was really new was that DITA was to become
the simplified form of XML that could replace complex SGML for documentation
markup.

 In 1998, JoAnn Hackos and Ginny Reddish published the definitive reference
on task analysis, User and Task Analysis for Interface
Design)<http://www.amazon.com/User-Task-Analysis-Interface-Design/dp/0471178
314/>,
and John Carroll published the edited proceedings of his 1995
workshop, Minimalism
Beyond the Nurnberg
Funnel<http://www.amazon.com/Minimalism-Technical-Communication-Multimedia-I
nformation/dp/026203249X/>,
with contributions by Hackos and Reddish.

 In 1999, IBM published an important guide, Publishing Quality Technical
Information (now unavailable). The team of writers included Fred Bethke,
whose earlier IBM Publishing Guidelines has established the importance of
task orientation.

 * The 2000's - IBM DITA

*
 In March 2001, IBM introduced DITA as a series of developerWorks articles
about a new simplified version of XML for documentation. It was intended to
replace IBM's IBMDoc, an internal version of SGML for IBM's technical
software support. While XML was enjoying great success as a data exchange
method (RSS and SOAP protocols), DITA was an attempt to make a simplified
XML starter set as a documentation markup language, one designed from the
outset to encourage reuse of small content components. The key ideas were to
be simpler than the complex SGML and also be usable online.

 In May 2002, IBM added domain specialization to topic specialization, and
demonstrated these in the Open Toolkit, a reference implementation of DITA
publishing, with a starter set of XSLT stylesheets. IBM encouraged authoring
tool vendors to integrate the Open Toolkit as a means of publishing DITA,
and most have done so.

 In 2003, two important books appeared on single sourcing and content reuse,
Single sourcing: Building Modular
Documentation<http://www.amazon.com/Single-Sourcing-Building-Modular-Documen
tation/dp/0815514913>,
by Kurt Ament, and Managing Enterprise
Content<http://www.amazon.com/Managing-Enterprise-Content-Unified-Strategy/d
p/0735713065Managing>,
by Ann Rockley.

 The same year, IBM revised and published PQTI as Developing Quality
Technical Information: A Handbook for Writers and Editors (2nd Edition)
<http://www.amazon.com/dp/0131477498/>, by Gretchen Hargis and others. This
book is all about DITA without mentioning the name, because IBM was using
DITA internally but not yet sharing it with the world when the book was
drafted.

 * OASIS DITA

*
 In April 2004, the Organization for the Advancement of Structured
Information Standards (OASIS), formed a Technical Committee to explore a
DITA Standard. The TC included XML tools vendors, consultants on Information
Architecture and Content Management Systems (CMS), and end users of the DITA
Document Type Definitions (DTD) and Schemas needed for the new DITA
Standard.

* DITA 1.0*
 DITA 1.0 was approved as an OASIS Standard in June 2005
 * DITA 1.1*
 DITA 1.1 was approved in August 2007, adding a new Bookmap specialization.
 * DITA 1.2*
 DITA 1.2 is expected sometime in 2008. It will add structured learning,
creation of Learning Objects with DITA, which will be compatible with
eLearning standards such as SCORM.

 *References*

A History of Technical Communications in the U.S., by R. John
Brockmann<http://www.amazon.com/Millwrights-Shipwrights-Twenty-First-Century
-Communication/dp/1572730773/>.


History of Outlining (and
STOP)<http://www.ditausers.org/history/OutlineHistory.html>.


Quick Reader Comprehension
(1961)<http://www.ditausers.org/history/QRC_Proposal_1961.pdf>.


Hughes STOP - Sequential Thematic Organization of Publications
(1965)<http://www.ditausers.org/history/STOPbeginnings.pdf>.


IBM Improving usability of publications
(1981)<http://www.ditausers.org/history/BethkeIBMpubGuidelines.pdf>.
Task-orientation HTML
version<http://www.ditausers.org/history/IBMTaskOrientedDocs.mht>

Writing Better Computer User Documentation
(1986)<http://www.amazon.com/Writing-Better-Computer-User-Documentation/dp/0
471884723/>

Mapping Hypertext, Robert Horn, Lexington Institute
(1989)<http://www.amazon.com/Mapping-Hypertext-Organization-Generation-Line/
dp/0962556505/>.


Developing Technical Training: A Structured Approach for Developing
Classroom and Computer-based Instructional Materials, Dr. Ruth Clark (1989,
2nd edition,
1999)<http://www.amazon.com/Developing-Technical-Training-Computer-based-Ins
tructional/dp/0787988464/>.


The Nurnberg Funnel, John M. Carroll, MIT
Press(1990)<http://www.amazon.com/Nurnberg-Funnel-Instruction-Communication-
Information/dp/0262031639/>.


Managing Your Documentation Projects <http://www.amazon.com/dp/0471777110/>,
by JoAnn Hackos (Wiley, 1994).

Standards for Online Communication <http://www.amazon.com/dp/0471156957/>,
by JoAnn Hackos (Wiley, 1997).

Robert Horn, Visual Language
(1998)<http://www.amazon.com/Visual-Language-Global-Communication-Century/dp
/189263709X/>.


User and Task Analysis for Interface Design, by JoAnn Hackos and Janice C.
(Ginny)
Reddish)(1998)<http://www.amazon.com/User-Task-Analysis-Interface-Design/dp/
0471178314/>.


Minimalism Beyond the Nurnberg Funnel, John Carroll, MIT
Press(1998)<http://www.amazon.com/Minimalism-Technical-Communication-Multime
dia-Information/dp/026203249X/>.


Two approaches to modularity
(1999)<http://www.ditausers.org/history/HornTwoApprchsModularity.pdf>.
Robert Horn compares structured writing to Hughes STOP.

Review of the Nurnberg
Funnel(1999)<http://www.ditausers.org/history/HornRvwOfNurnbrgFnnl.html>Robe
rt
Horn compares structured writing to Minimalism.

The Impact of Single Sourcing and
Technology<http://www.rockley.com/articles/Single_Sourcing_and_Technology.pd
f>,
Ann Rockley, 2001.

Cisco/Clark Reusable Learning
Objects<http://www.ditausers.org/history/CiscoClarkRIO.pdf>.


Managing Enterprise
Content<http://www.amazon.com/Managing-Enterprise-Content-Unified-Strategy/d
p/0735713065Managing>,
by Ann Rockley, New Riders, 2003.

Single sourcing: Building Modular
Documentation<http://www.amazon.com/Single-Sourcing-Building-Modular-Documen
tation/dp/0815514913>,
by Kurt Ament, Andrew Publishing, 2003.

Robert Horn Powerpoint on Visual
Language.(2003)<http://www.ditausers.org/history/BobHornGlasgow.ppt>.


Developing Quality Technical Information: A Handbook for Writers and Editors
(2nd Edition) <http://www.amazon.com/dp/0131477498/>, by Gretchen Hargis,
Michelle Carey, Ann Kilty Hernandez, Polly Hughes, Deirdre Longo, Shannon
Rouiller, Elizabeth Wilde (IBM Press, Information Management Series, 2004).

Information Development: Managing Your Documentation Projects, Portfolio,
and People <http://www.amazon.com/dp/0471777110/>, by JoAnn Hackos (Wiley,
2006).
______________________________

Apologies for the very long post. I hope TECHWR-L allows it and that it
proves valuable for some of you.

Cheers,

Bob

-- 
Bob Doyle
Editor In Chief, CMS Review - http://www.cmsreview.com
Founder, DITA Users - http://www.ditausers.org
Former Technology Advisor, CM Pros -
http://www.cmprofessionals.org/membership/cm-profiles/bob-doyle
Contributing Editor, EContent Magazine -
http://www.econtentmag.com/Articles/ArticleIndex.aspx?ContextSubtypeID=71
President and CEO, skyBuilders - http://www.skybuilders.com
77 Huron Avenue
Cambridge, MA 02138
Tel: +1 617-876-5676 Skype:bobdoyle


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info.