OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

RE: Open Source XML Editor

True.  But remember that when you make the DTD/Schema 
drive the editor, you may be mixing the data structures 
and the document structures (sure you can use XSLT to 
get around some of this).  Some like this kind of 
editing, but the structures make a lot of difference.  
DTDs that had to cover a family of documents produce 
bizarre complex editing paths.   So the analysis is 
very important both in the lifecycle path of the 
information and the workflow of the production staff. 
Problems like this lead to a lot of the early thinking 
about enterprise wide markup systems.

Michael's examples reflect programming 
documentation.  Of the types of technical information 
I've worked with, it is the easiest.  The 
harder bits tended to be the hardware systems with 
the extensively indexed and cross-referenced drawings 
combined with repair and assembly.  Software and the 
the software authors are a piece of cake by comparison.

What Alshuler missed as I recall was that many tech 
writers were stuck like tractors in a muddy bog by 
the writing standards they had been using.  It was 
part of the problem of the 38784/28001 roadblocks 
put up to doing interactive technical manuals. They 
did not want to code the tags to begin with, then 
when they began, they immediately replicated all 
of the problems for which they were the owners 
of the solutions.  So even if the markup was easy, 
the mindset was wrong.  

Today, the almost shocking thing is that 
so many of them won't give up WinHelp or WinHelp tools. 
A LOT of software companies are still grinding out 
hypertext that is mundane and production-intensive because 
the tech writer leads and their managers refuse to use 
database-driven systems.  So customers request paper 
copies for various good reasons and these companies 
refuse to give them source that would enable this 
and claim that everyone knows that digital is the 
only way to go.   They defend that ferociously 
as a cost savings for the customer all the while 
really defending their own arcane methods.  Fact 
is, it's a con.  A decent hypertext format with 
transforms lets any device get the information 
as needed in the format needed and that includes 
the old devices... like paper.

Own the solution?  Defend the problem.

Len Bullard
Intergraph Public Safety

Ekam sat.h, Vipraah bahudhaa vadanti.
Daamyata. Datta. Dayadhvam.h

-----Original Message-----
From: Marcus Carr [mailto:mrc@allette.com.au]

Michael Smith wrote:

> Even with the best editing app in the world, I think document authors
> find structured authoring simple only when the content they need to
> mark up is simple -- that is, it has a simple structure and lacks a
> variety of discrete classes of "objects" that need to be marked up.
> Marking up technical documentation, for example, is inherently
> difficult because it has a relatively complex structure and variety of
> discrete kinds of objects -- variables, filenames, code examples, and
> so on -- that authors must recognize and mark up appropriately.

I agree, and would even go further. Liora Alshuler wrote a great article
ten years ago about how writers aren't necessarily at all intimidated by
markup. After all, they have a lot of understanding about what they're doing
they probably wouldn't be writing about the topic if they didn't. The moral
was to spend time on the analysis, and design a succinct and appropriate
structure in concert with the writing team. Then even "complex" documents
not be difficult to author to. A good "guided syntax editor" is an
tool for a system like this.