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