RE: Directions for tomorrow's techwriting

Subject: RE: Directions for tomorrow's techwriting
From: "Rebecca Downey" <rdowney -at- matrox -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 23 Apr 2002 09:31:09 -0400


Hi.

Just to add to Bernd Hutschenreuther's excellent list of items:

Internal localization
---
The difference between documentation and code base in software will be
marginalized so that things like error and log messages can be easily
incorporated into the documentation as they are changed/updated. This, by
the way, is one of our office's attempts at using XML.

The message and the relevant documentation about it will be written in XML.
The programmers can then strip out the information they need using a fairly
straight forward XLST. When programmers need a new message - they can add it
and it will be flagged the next time the technical-writer looks at their own
XLST. The technical writer can then fill in the blanks, correct the English
and (in our case) use bug-tracking software to notify the programmer that
the work is done. This allows the programmer to spend more time programming
and less time fussing with English.

Ideally (and here's the future bit) - string tables and other GUI related
text would also be in XML; this would allow the technical writers to obtain
a list of fields (radio buttons, text descriptions, etc) through their own
XLST. Again the goal would be easier communication between the programmers
and the technical writers when things need to be changed.

The technology is available for this right now; and it should be fairly
straight forward to implement. The only true stumbling block is in relation
to the compilers and their "visual" elements for the GUI. Specifically
Visual C/C++ and it's RC file. Ug.

---
In short I see the future of technical writing, not in fonts or software
tools, but in methodology. Already manuals are improving as writers learn to
perform user-samplings (testing the ease-of-use of both the interface and
its supporting documentation). The next step is to ease communications
between the technical writers and the programmers/SMEs.

While users are important to end-user documentation stratagems, I find that
the programmers/SMEs tend to be left out of these methodologies. Since they
are, and will remain, the primary source of information for any
technical-writer; solutions that ease communication between these two camps
can only benefit technical writing as a whole.

Just my 2c.
-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Rebecca Downey Senior Technical Writer
ITG:NBM Matrox Electronic System
1055 St Regis, Dorval, Quebec, H9P 2T4



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr

Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

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

References:
Directions for tomorrow's techwriting: From: Bernd Hutschenreuther

Previous by Author: RE: Why don't technical writer's do case studies?
Next by Author: RE: Directions for tomorrow's techwriting
Previous by Thread: Directions for tomorrow's techwriting
Next by Thread: RE: Directions for tomorrow's techwriting


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


Sponsored Ads