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 documentation.

For those with strong opinions, here's the layout:
- Background
- Train of thought
- Proposed solution
- Question
- Conclusion

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,
stand-alone database.
- 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.).

Proposed solution
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 DTD.

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 proposed solution?
- 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 listserv.

Thanks in advance.

Cheryl Bryant
Technical Lead/Programmer-Writer
Black Diamond, WA
mailto:cheryl -at- bryantent -dot- com

Chat with friends online, try MSN Messenger:

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!

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 :

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 for more resources and info.

Previous by Author: Re: "Grammar Stinks."
Next by Author: Re: Tuesday's news: cost-cutting measures
Previous by Thread: Drafts and workplace assumptions
Next by Thread: Wanted: Newbie Advice

What this post helpful? Share it with friends and colleagues:

Sponsored Ads