Follow-up: organizing DTD <element> and interface information

Subject: Follow-up: organizing DTD <element> and interface information
From: "Lisa Wright" <liwright -at- earthlink -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 9 Jul 2003 00:30:36 -0700

A couple of weeks ago I asked for information on embedding XML tag
information in screen documentation. Thanks to all those on- and
off-list for your great advice. Thought I'd share the solution I came up

Short term (which turned out to be a few hours), I followed each screen
element with its <element> tag. Then I created a separate, 2-level index
using cross-posting just for the XML elements that attempts to show
parent/child relationships. Developers can see the screen context in the
screen section or just look up by element.

Medium term (middle of next week), I've added the parent/child
relationships to the screen section, after running it by a couple of
programmers who emphasized that they like context. I've kept the index,
which is cited as very helpful.

Long term (a couple of months), I will be documenting the DTD or XSD.
Full-blown reference material, to be modeled on Docbook or similar XSD
documentation. Will also be keeping and improving if I can the
contextual documentation.

I have over the course of the last week been able to glean some more
details about what the customer intends to do with the information, so I
am no longer operating in complete darkness. Thanks again to the list
for being my flashlight whilst I groped for the switch!


-----Original Message-----
From: Lisa Wright [mailto:liwright -at- earthlink -dot- net]
Sent: Sunday, June 29, 2003 11:04 AM
Subject: organizing DTD <element> and interface information

Hi guys,
I have a situation here, and I need a little help. Hopefully someone has
had to do this before and can give me some advice.

On my new contract I am documenting an application where the users do
their development in a graphical interface, push a button, and
bingo-presto, an XML file is written.

The fields/screens have all been documented in an appendix of the
application guide. But now a client is requesting to have documented
"the relationship of the screens to the XML elements."

I have the DTD and two XML output files. My thought is to simply add the
<element> name to each field/screen description. I'm not sure who the
specific audience is for this particular information. It could simply be
a hoop we're having to jump through; it could be business analysts;
possibly developers. It was simply presented to me as a contract

Anyone have any other thoughts? My only concern with this method is that
it is very screen-centric. Should I also create a version that goes from
the DTD-to-screen side? This would be documenting everything twice...but
only going one way might not be best for all possible audiences.

Thanks for any and all suggestions.



Create professional Help systems that feature interactive tutorials and
demos with all new RoboHelp Studio. More at

Mercer University's online MS Program in Technical Communication Management:
Preparing leaders of tomorrow's technical communication organizations today.
See or write George Hayhoe at hayhoe_g -at- mercer -dot- edu -dot-

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: Content management for Word documents?
Next by Author: RE: ADMIN: Civility and content
Previous by Thread: Re: hyphenated word grammar question
Next by Thread: Re: techwr-l digest: July 08, 2003

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

Sponsored Ads