TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Giving up on XML From:"Bob Doyle" <bobdoyle -at- skybuilders -dot- com> To:"eric -dot- dunn -at- ca -dot- transport -dot- bombardier -dot- com" <eric -dot- dunn -at- ca -dot- transport -dot- bombardier -dot- com> Date:Fri, 16 Mar 2007 16:33:59 -0400
Hi Eric and all,
>
> You can?t allow the common reference to be a misrepresentation. There?s a
> basic minimum that needs to be learned. The relationship between XML,
> DTDs, implementations, and Tools would, IMO, be that bare minimum.
> Because only once that is understood can it be determined if the problems
> or misunderstandings lie in configuring/installing a tool, understanding
> the structure of a specific implementation (HTML, DITA, Docbook), or else
> where.
Let me provide some background toward that basic minimum of learning.
XML is a very general markup language. Like SGML (standard generalized
markup language), it needs a list of the allowable content elements against
which a document is "validated.".
This is the DTD (document type definition), also called the content model -
a list of allowable elements, what order they can be in, how many are
allowed of each, etc. It's like the EDD (element definition document) of
Framemaker, which (unfortunately) also includes the styles information.
Modern good practice is to separate presentation from content.
To produce output, XML uses XSLT (a stylesheet and transformation language -
and a procedural programming language written in XML itself).
So XML has three levels, the allowed structure and content model (DTD, the
content itself (XML), and the presentation styles (XSLT). HTML mixes all
three together. Framemaker mixes content model and styles.
A bit of history.
XML was standardized in 1996 -a kind of cross between HTML and SGML.
Over 10 years earlier, SGML was the latest version of GML. It's best known
tool is DocBook, which was designed for book format documentation.
IBM used SGML and DocBook for their documentation. Then they used XML and
DocBook.
Then they realized that technical documentation should no longer be in book
format!
Rather it should be written in reusable chunks.
The idea of chunking technical documentation goes back to the 1960's and
Information Mapping (http://www.infomap.com). Information Mapping
recognized many Information Blocks (chunks), Information Maps (arrangements
of blocks), and Information Types.
Around 2000, IBMs documentation writers limited the Information Types to
only four. They then created a relatively simple DTD with only a couple of
hundred allowable language elements in these types. http://www.ditausers.org/resources/dita_elements
The basic general type is called a "topic." Writing reusable chunks is now
called topic-based authoring.
They then "specialized" this generic topic (remember biological inheritance
- taxonomy of species?) into concepts, tasks, and references.
They called it Darwin (see why?) Information Typing Architecture or DITA. It
consists of topics and maps.
DITA maps are like magical tables of contents, really just lists of links to
topics (links are called topicref, analogous to hyperlink hrefs).
You rearrange your topicrefs in a ditamap, build (process) the map, and out
comes a new document (in Help, HTML, PDF or other formats).
IBM and many other organizations invested many man years and millions of
dollars creating DTDs to use with XML. But the generality and eXtensibility
proved way to flexible. It was very difficult to get agreement on DTDs.
The genius of DITA is that created one basic DTD (actually a small set) and
also a set of XSLTs. They implemented all their tech docs in them.
Then gave them away as open source to be maintained by OASIS (Organization
for the Advancement of Structured Information Standards). http://www.dita.xml.org.
They gave them to you and to me, so we would not have to hassle with our own
DTDs.
The XSLTs they collected into a processing engine called the DITA Open
Toolkit, which builds DITA topics and maps into multi-channel publications,
print, web, help, etc.
Many of the concerns of techwhirlers expressed in this thread about Giving
Up on XML were experienced by IBM years ago.
They are way past those concerns and so should we be.
As to the tools needed to work with DITA, last year I reviewed the top 12
XML editors, identifying those that do DITA. http://www.cmsreview.com/XML/Editors.
And I am now developing a web-hosted toolset with the DITA Open Toolkit
running on a server, and a browser-based editor called DITA Storm ( http://www.ditastorm.com), so tech writers can get started with DITA and
topic-based structured writing - without knowing XML, and without writing a
DTD or an XSLT.
Please help us to build this hosted learning environment and collaborating
community.
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList
Now shipping: Help & Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help & Manual: http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
