Re: [dita-fa-edboard] History of DITA and modular documentation

[Michael Priestley <mpriestl@ca.ibm.com>]

A few thoughts:

modular docs go back to the 50/60s at
least - see STOP methodology, which was a big influence on aerospace docs:
        http://www.theprices.com/4artTW11.htm
minimalist docs go back to the 80s,
and have been empirically validated as an approach many times:
        http://tip.psychology.org/carroll.html
        http://portal.acm.org/results.cfm?coll=portal&dl=ACM&CFID=21509772&CFTOKEN=28875284

the two major updates that jon has apparently
missed since 1978 that have affected the apparent viability of modular
docs are online help and the WWW
        
my personal introduction to modular
documentation was in the context of online help:
        http://www.horton.com/html/dwoldbook.aspx
IBM's standardized approaches to developing
quality information also focus on modular content - IE, modular content
is not at odds with quality, in fact it is necessary for quality:
        http://www.amazon.com/Developing-Quality-Technical-Information-Information/dp/0131477498
        
In most of the tech docs world, modular
docs are a solved problem - all DITA topics do is enshrine well-known and
accepted best practices. The interesting stuff is happening in areas like
information architecture, where, now that structure above the topic level
as been appropriately abstracted, the design of those inter-topic relationships
can be treated as a full-fledged discipline in its own right (in DITA's
case, using DITA maps):
        http://iainstitute.org/

And that's not even getting into specialization
:-)

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

"Bob Doyle" <bobdoyle@skybuilders.com>

05/02/2007 02:56 PM

To	"DITA Editorial Board" <dita-fa-edboard@lists.xml.org>
cc
Subject	[dita-fa-edboard] History of DITA and modular documentation

Hi all,

I am wondering if some of you can help me with a history of modular documentation
in general and DITA in particular.

Among other things, I would like to respond in a column to some negative
remarks made by Jon Bosak in his closing keynote for the recent XML 2006
conference in Boston. 
http://2006.xmlconference.org/proceedings/162/presentation.html

Jon said

"Another ancient subject that seems to be popping up again is the idea of modular document creation. This is one of those concepts that comes through about once a decade, seduces all the writing managers with the prospect of greater efficiency, takes over entire writing departments for a couple of years, and then falls out of favor as people finally realize that document reuse is not a solvable problem in document delivery but rather an intractable problem in document writing — which is, how to retain any sense of logical connection between pieces of information while writing as if your target audience consisted entirely of people afflicted with ADD.

"I could go on at length about this, but instead I'll simply leave you with the observation that my personal love affair with modular documentation occurred in 1978 and that I haven't seen a thing since then that would change the conclusions I reached about it almost thirty years ago. This is not to say that I'm trying to discourage the technical writing community whence I came from their enthusiasm for the modular authoring technology du jour, since engagement in such efforts is virtually guaranteed to buy tech writers a few years in which they can act like software engineers and present themselves as engaged in cutting-edge informational technology development rather than plain old technical writing. That strategy has worked great for some of us."

I think I have reasons why DITA is different, but wish I had more details on the failures Jon has seen over the years. Can we explain why DITA is not just the modular documentation du jour?

I also hope to give a clear account of why DITA has three primary information types. I trace them to my experience with documentation for Apple Macintosh, but it may have an earlier origin?  As I write (speculating)  in an upcoming article for STC Intercom

Experienced writers will recognize the three information types - concepts, tasks, and reference - as the three great user manuals of the golden age of software, when you did read them in order. Apple called them Learning X, Using X and the X Reference. My first tech docs were the user manuals for my MacPublisher, which shipped in the year of the Mac, in English, French, German, and Italian. To this day, many O'Reilly books follow the triad of Learning X, Programming X, and X - the Definitive Reference. Minimalism has moved the primary documentation focus to the practical "how-to" kind of knowledge we discover by user and task analysis. Today's impatient users are not so interested in learning the theory and overview, they want the instant gratification of problem solutions.

Who at IBM (if anyone takes credit) named it Darwin? How clearly did it borrow from Object-Oriented Programming, etc.?

When they chose Information Typing, was there awareness of Information Mapping's decades of work?

Did the DITA Architects overlap with John Carroll and his Minimalism team at IBM?

Thanks in advance for any pointers, to people or documents - modular or traditional.

Cheers,

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