[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message]

RE: Who Is Teaching XML To Technical Writers?

• From: "Len Bullard" <Len.Bullard@ses-i.com>
• To: "Mike Sokolov" <sokolov@ifactory.com>
• Date: Fri, 10 Aug 2012 13:12:24 -0500

Good question, Mike.  I'm not sure it is manual although that is how I
found it.  I'm editing in Notepad++; faster and I can see the error
patterns; and parse checking on load and after changes.  It's old school
but it has advantages and one is to find stuff like this.

Probably the editor isn't checking for this on-entry. Arbor Text allows
it and then it's caught if they use id checking (DUPLICATE).  However, I
suspect the training is lacking in lots and lots of logistics
departments.  This is the "tagging" culture and it is actively harmful.

XML plus a DTD/Schema is a fine QA tool if you know how to use it.
Unfortunately, the process that seems to prevail is they generate
everything in Word or some other WYSIWYG editor and tag AFTER the
validation/verification process.  And then the XML isn't quality checked
until the customer gets it.  So the process is backwards.  They do this
rather than train the writers and buy them tools.  Also many of these
people aren't trained writers.  They are repurposed technicians or floor
workers.

Then it is possible the customer isn't creating a product from the
delivery through a process that catches this.  Imagine a hypertext
product that instead of using the internal referencing is actually
grabbing tag chunks using basic regex-like tools, wrapping it in
processing instructions and relying on a shadow referencing system after
that, possibly to defend against exactly this problem.   Meanwhile the
contractor is delivering XML plus PDF and only the PDF is being examined
for formatting problems.  The format is added by FOSIs and then a PDF
converter or XSL-FO to PDF.

IOW:

1.  The QA processes of both the customer and the contractor are wholly
oriented toward a well-formatted deliverable.   This means local style
Nazis using local style preferences prepare the content and spend
enormous resources formatting it in ways that are both wrong and will be
thrown away during the XML tagging process.  The taggers attempt to
crunch the XML into looking like the Word.  I just restructured a
document that was one paragraph filled with a few hundred nested
sequenced and random lists with labels because the tagger was given an
air force manual that still numbers topics.  Army TMs don't do this but
the tagger has a DTD that gives them no other choice.  

2.  Because the WYSIWYG products are used throughout the processes until
the very end, neither the customer nor the contractor are validating or
verifying the final deliverables.  They think they are but they aren't.


3.  And Guess What?  They still get the ISO 9000 certifications because
ISO isn't smart/savvy enough to notice that when XML is delivered but
only "tagged", it actually isn't QA checked.

The stuff I am finding astounds me. The QA is deficient in the extreme.

The customer pays a lot for poor quality.  The universities are making
this worse by the way they train technical writers in XML as a sort of
two-hour morning course overview after a semester of HTML.  Worse, they
give them DITA, CSS and a smattering of DTD overview.  That might be ok
if they were leaving to build web pages, but in the MIL world of 40051,
most of that is useless.  They need rigorous training in DTDs, XML and
DTD data types, XSLT, and the actual type definitions they will be
applying because these DTDs are orders of magnitude more complex than
what they will encounter on the web. 

In short, some are trained but as if they were going to write software
by people who do write software, and that is not what they actually do
for a living.

len

-----Original Message-----
From: Mike Sokolov [mailto:sokolov@ifactory.com] 
Sent: Friday, August 10, 2012 12:47 PM
To: Len Bullard
Cc: xml-dev@lists.xml.org
Subject: Re:  Who Is Teaching XML To Technical Writers?

Why are technical writers generating ids manually?

sokolov

On 08/10/2012 11:48 AM, Len Bullard wrote:
> <step1 id="F19T5BP12"><para id="F19T5BP12">...
>
> Fail.
>
> len
>
>
_______________________________________________________________________
>
> XML-DEV is a publicly archived, unmoderated list hosted by OASIS
> to support XML implementation and development. To minimize
> spam in the archives, you must subscribe before posting.
>
> [Un]Subscribe/change address: http://www.oasis-open.org/mlmanage/
> Or unsubscribe: xml-dev-unsubscribe@lists.xml.org
> subscribe: xml-dev-subscribe@lists.xml.org
> List archive: http://lists.xml.org/archives/xml-dev/
> List Guidelines: http://www.oasis-open.org/maillists/guidelines.php
>
>    

• References:
  • Using the concepts of Category Theory to create better XML datamodels
    • From: "Costello, Roger L." <costello@mitre.org>
  • Re: Using the concepts of Category Theory to create betterXML data models
    • From: David Sheets <kosmo.zb@gmail.com>
  • RE: Using the concepts of Category Theory to createbetter XML data models
    • From: "Costello, Roger L." <costello@mitre.org>
  • OT: When Spell Checkers Strike
    • From: "Len Bullard" <Len.Bullard@ses-i.com>
  • Who Is Teaching XML To Technical Writers?
    • From: "Len Bullard" <Len.Bullard@ses-i.com>
  • Re: Who Is Teaching XML To Technical Writers?
    • From: Mike Sokolov <sokolov@ifactory.com>