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.
Solicitation for opinions on an XML WYSIWYG (was: xml/docbbok editors)
Subject:Solicitation for opinions on an XML WYSIWYG (was: xml/docbbok editors) From:"Cheryl Bryant" <acherylb -at- hotmail -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Tue, 24 Sep 2002 16:54:22 +0000
I may have stumbled onto a solution that removes the XML burden from writers
who don't want to be bothered with it. (Some do, some don't.) To determine
if it has any merit, I'd like to hear opinions about authoring XML-ized
For those with strong opinions, here's the layout:
- Train of thought
- Proposed solution
I'm a technical lead and senior programmer-writer. My development background
is rooted in databases, text parsing, and structured object-oriented
programming. (Not a typo.) I'm a *staunch* user experience and human factors
advocate. For years I struggled with the practicalities of implementing XML
within a documentation development environment.
Train of thought
- A raw XML data file is nuthin' but an ASCII text, hierarchical,
- XML technologies (XSLT, XPath) are the means by which raw XML data
is transformed into renderable content (browsers, print, etc.).
- API documentation is mostly data-based (perfect for database
storage/retrieval and output to XML).
- Authoring processes for conceptual and procedural content types are
fluid, not data-based.
- Current XML documentation systems force writers to:
Author in a raw HTML-like manner (using XML tags, instead of
HTML tags), in a highly structured (SGML-like) fashion.
Purchase an immature WYSIWYG tool (plus training costs/learning
curves), and you still don't get the precise control you need
e.g., whitespace, indenting, etc.).
I recently engineered a design for an XML- and SQL-based system for
content/documentation development and production. This would allow writers
to write, edit, and tech review using their favorite authoring environment
and established processes. There'd be virtually no change to the way you
think, express, or process your content. You wouldn't need to purchase,
learn, or integrate any new tools in your authoring environment.
Yet you'd still have great control over your XML-ized output. And if you
want to, you can integrate any of the pre-fab DocBook XSLT stylesheets and
Better still, you can integrate application software content (such as UI
element names, like the name of a UI button) into your authoring
environment, without programming anything. When you generate the docs, the
UI element names are automatically updated in the output.
Based on your experience with XML documentation systems (or your need to
move docs toward an XML-based solution), what's your reaction to such a
- From a user's (writer's) perspective.
- From a manager's (business case) perspective.
- From a devil's advocate perspective.
The system I propose is in design. There is no "product" (yet). As a user
advocate, I am very interested in hearing reactions to this, especially
strong opinions for or against such a system. I will build this feedback
into the design. (Why build a system nobody wants to use?)
You can either email me off list (cheryl -at- bryantent -dot- com), or via the
Thanks in advance.
Black Diamond, WA mailto:cheryl -at- bryantent -dot- com
Chat with friends online, try MSN Messenger: http://messenger.msn.com
Experience RoboHelp X3! This new RoboHelp release combines single sourcing,
print-quality documentation, conditional text and much more, into the most
monumental release of RoboHelp ever! http://www.ehelp.com/techwr-l
Enhance, optimize and automate your FrameMaker-to-PDF workflow with TimeSavers:
Define all PDF features in your source FrameMaker files ONCE, distill MANY.
Bookmark Controller, Link Controller, UnBloat & more : http://www.microtype.com
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.