Organizing DTD <element> and interface information?

Subject: Organizing DTD <element> and interface information?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 2 Jul 2003 08:49:09 -0400


Lisa Wright is <<... 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.">>

Before we can provide any really valid advice, you need to tell us what the
client wants to do with the relationships. Once you know that, you can
design to fit. If you can't talk directly to the client, talk to the person
who _did_ talk directly to the client; they can give you a clearer idea of
what your goal should be. Better still, you can create a proposal based on
your understanding and ask the client to approve it before you begin work.
Plan twice, cut once!

<<I have the DTD and two XML output files. My thought is to simply add the
<element> name to each field/screen description.>>

That's probably a good solution. Alternatives might include: a graphic of a
typical output document, with callout arrows pointing to various components
of the output and explaining how those relate to the XML; an HTML document
that lets you link from an image map of the GUI to the XML; a database that
does the same thing; and so on. Form follows function: if you know how
they'll use it, then you know how to design it.

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

My second and third suggestions (the HTML approach and the database) could
both be easily adapted to work in both directions. Write the information
once, then simply provide a different front-end (e.g., a table of contents).

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada

"If you were a member of Jesse James's band and people asked you what you
were, you wouldn't say, 'Well, I'm a desperado.' You'd say something like,
'I work in banks,' or 'I've done some railroad work.' It took me a long time
just to say, 'I'm a writer.' It's really embarrassing."--Roy Blount, Jr.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ANNOUNCING ROBOHELP STUDIO
Create professional Help systems that feature interactive tutorials and
demos with all new RoboHelp Studio. More at http://www.ehelp.com/techwr-l2

Mercer University's online MS Program in Technical Communication Management:
Preparing leaders of tomorrow's technical communication organizations today.
See www.mercer.edu/mstco 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
http://www.raycomm.com/techwhirl/ for more resources and info.



Follow-Ups:

Previous by Author: RE: ADMIN: Civility and content
Next by Author: Has anyone reviewed or edited using PDF marked up by Acrobat tool s?
Previous by Thread: [techwr-l-daily-announce] TECHWR-L Daily Update Posting
Next by Thread: printing from press--divide by 4 or 8 question


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


Sponsored Ads