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.
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
with.
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!
Lisa
-----Original Message-----
From: Lisa Wright [mailto:liwright -at- earthlink -dot- net]
Sent: Sunday, June 29, 2003 11:04 AM
To: 'TECHWR-L'
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
requirement.
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.
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.
