freelanceprogrammers.org Forum Index » XML / XSL
Re: Docbook Editor
Joined: 29 Jun 2000
Posts: 1
"Today, Postscript; tomorrow XML" [XML in the New
XML in the News...
Included in this message is a recent news story titled,
"XML moves to the mainstream." The final section, "Today,
PostScript; tomorrow, XML" is especially interesting.
To access the original HTML version of the story, visit:
http://dailynews.yahoo.com/h/zd/20000626/tc/xml_moves_to_the_mainstream_1.html
------------------------------------------------------------------
XML moves to the mainstream
By Andreas Pfeiffer, the Pfeiffer Report on Emerging Trends and
Technologies, Special to ZDNet [Monday June 26 02:16 PM EDT]
.................................................................
Already a vehicle for high-end content and asset management on
the Web, the industrial-strength markup language is poised to
break into shrink-wrapped applications.
What is happening with Extensible Markup Language?
Over the past few years, the markup language derived from SGML
(Standard Generic Markup Language) has gained a lot of ground
in high-end information-management applications. Lately, XML
has also become an industry buzzword, a must-have feature for
anybody working in modern content-processing applications.
While XML has been the backbone for high-end applications for
some time, the market for shrink-wrapped XML products is also
starting to take off.
Quark Inc. just shipped avenue.quark, its XML import/export
extension for QuarkXPress. Meanwhile, Adobe Systems Inc.
(Nasdaq:ADBE - news) has released FrameMaker 6.0, which exports
(but doesn`t import) XML and has announced XML support for the
next version of Golive, to name just a few examples.
As for Microsoft Corp. (Nasdaq:MSFT - news), the company`s
recently announced .Net strategy for Internet-based services is
also based on XML.
Twenty questions
Is there a low-end XML market? What strategies should software
developers use to jump on the XML bandwagon? Will XML simply
stay a data format, or is there an emerging market for XML
applications?
There`s no quick and easy answer to these questions. XML is a
very powerful tool, and it has proven over and over that as far
as data interchange goes, it has a lot to offer.
In recent years, XML has become the de facto standard for
high-end content and asset management. Therefore, it`s not
surprising that more and more software developers are flocking
to support it.
We are currently going through a trend of media consolidation,
both on the corporate level and as far as end users are
concerned. High-end applications are increasingly required to
support XML. But where is the low end of the market going?
And for developers, is there room for an XML killer app?
Quark`s XML avenue
Quark is giving the market a shot with avenue.quark, which will
also be part of XPress 5.0. avenue.quark is an extension for
XML import and export that angles for high-end integration of
XPress-based content with XML-based Web-authoring systems such
Vignette Story Server.
It is also a showcase application to demonstrate that Quark is
moving full steam into cross-media publishing. It will be
interesting to observe whether avenue.quark will build a user
base outside its captive audience, namely high-end Web content
managers who need to integrate XPress-based content with their
data-serving applications on the Web.
For the main publishing market to move seriously to XML-based
data structures, it will be necessary to re-engineer the
applications and proprietary data structures extensively. This
won`t happen overnight. For example, while avenue.quark will
outfit XPress 5 with XML import and export, there`s little to
indicate that the XPress file format will be rewritten to move
closer to XML-based structures.
As for Adobe, the company`s official position on XML is not
very clear yet either, despite its moves to embrace established
standards.
Who needs it?
For software developers, it is important to assess how much XML
support and development will be needed in order to stay ahead
of the market. And that in turn will depend on whether XML data
structures can move beyond the realm in which they have
acquired standard status.
Does the end user need XML? More importantly, does the end user
think he needs XML? Market perception can be as important as
genuine need for a an emerging technology.
Interestingly, XML reverses the common pattern of technology
adoption that has driven much of the high-tech market.
Practically all tools that have gained predominant market
position have evolved from the ground up, starting their
careers as end-user applications and then becoming increasingly
professional. If XML moves beyond vertical, high-end
applications, its progress will represent the inverse of that
standard operating procedure.
In the end, whether or not the markup language becomes
pervasive beyond the high end of content management will also
depend on software developers.
Today, PostScript; tomorrow, XML
Right now, there is a consensus that XML is complex and needs
specially trained operators. Nevertheless, PostScript drawing
packages and other applications have demonstrated that it is
indeed possible to make complex, programming-based processes
reasonably simple to use.
XML is today where PostScript was before the arrival of Adobe
Illustrator: a programming language that could be manipulated
through a number of specialized utilities -- but did not really
have much end-user functionality.
For XML to become as much a standard as Adobe`s
page-description language will require strong development
efforts as well as broad end-user interest and education, which
only happens when products move into the highly competitive
realm of shrink-wrapped software.
The market is not there yet, but XML is not going away. We are
living in a world where non proprietary data-structures have
become essential to an increasing number of users. What really
remains to be seen is which of the industry players will be
capable of capturing and focusing this growing market interest
with an XML killer app.
.................................................................
Andreas Pfeiffer is an industry analyst and editor in chief of
the Pfeiffer Report on Emerging Trends and Technologies.
Joined: 13 Jun 2003
Posts: 39
Re: Docbook Editor
> I keep a look out for a decent (non-Emacs - can`t get one with it <g>)
> Editor and have tried those suggested so far without satisfaction.
I have to agree about Emacs. ;-) For those of us who prefer vi-style
editors, Vim has an xml-plugin module. Using the plugin, tag-based
editing was more pleasant than I thought it would be.
Graphical editors have several advantages, including context-sensitive
tag selection and making sure your document stays at least well-formed,
but this will do until I find Ultimate Vapor`s XML Nirvana editor. :-)
--
Larry Kollar, Senior Technical Writer, ARRIS
"Content creators are the engine that drives
value in the information life cycle."
-- Barry Schaeffer, on XML-Doc
Joined: 13 Jun 2003
Posts: 39
Re: Docbook Editor
>> = Sebastian Rahtz
> = Isaac Rabinovitch
>> ... what if I find it easier to edit my writing stuff which is
>> temporarily invalid? for instance, I might write 6 list items quickly,
>> then go back and top and tail them with a list tag.
>
> Well, I guess you have no problems with the
> write-test-fiddle-test-fiddle-test... thing. But it would be
> unacceptable in most organizations I`ve worked for. Too hard to train
> new writers on the system.
I`ve been converting a horribly messy Word doc to structured
FrameMaker the last few weeks. I ended up using a handful of
shell scripts (well, one was an awk script because it was a
bit more complex) to wrap tags around selected pieces, then
importing the XML into FrameMaker. It was *much* faster than
wrapping text by hand.
What Sebastian talked about is similar -- bang out a series
of list items, then go back and pipe them through a script
to add tags.
> One exception is a contract I did five years ago -- writing a manual in
> TROFF!
The nice thing about *roff formatters is that the tags are
generally so short that you can insert them on the fly without
the mental pauses that many other formatting languages seem to
require. A macro package like -mm expresses the structure well
enough that converting to XML (and back) is possible; see ESR`s
doclifter script for an example.
This discussion suggests to me a two-stage approach: compose
original text using very simple markup -- perhaps something
similar to a Wiki language -- then use a script to convert it
to proper XML for editing & formatting.
--
Larry Kollar, Senior Technical Writer, ARRIS
"Content creators are the engine that drives
value in the information life cycle."
-- Barry Schaeffer, on XML-Doc
Joined: 05 Aug 2003
Posts: 21
Re: Docbook Editor
larry.kollar@... wrote:
>I`ve been converting a horribly messy Word doc to structured
>FrameMaker the last few weeks. I ended up using a handful of
>shell scripts (well, one was an awk script because it was a
>bit more complex) to wrap tags around selected pieces, then
>importing the XML into FrameMaker. It was *much* faster than
>wrapping text by hand.
>
>What Sebastian talked about is similar -- bang out a series
>of list items, then go back and pipe them through a script
>to add tags.
>
Except Sebastian is talking about authoring the original document, and
you`re talking about converting from an unstructured format. You
*expect* the latter to be complicated and done by somebody who`s
technicallly sophisticated. But hacking out a script for day-to-day
writing is less acceptable.
>The nice thing about *roff formatters is that the tags are
>generally so short that you can insert them on the fly without
>the mental pauses that many other formatting languages seem to
>require. A macro package like -mm expresses the structure well
>enough that converting to XML (and back) is possible; see ESR`s
>doclifter script for an example.
>
I`ve had this conversation before, only with LaTeX zealots. *All*
non-structured formats *support* two-way conversion. (LaTeX and TROFF do
it with macros, word processors do it with "styles".) That doesn`t mean
it`s *practical*. Writers, being mere carbon-based units, tend to break
structure rules: they forget, or they misunderstand a rule, or the rule
isn`t clearly stated, or they just can`t be bothered. The whole point of
using a structured format like Docbook is to prevent this noise from
creeping in. Treating Docbook XML as "just another format" and trying to
do maintenance in other formats defeats the purpose.
>
>This discussion suggests to me a two-stage approach: compose
>original text using very simple markup -- perhaps something
>similar to a Wiki language -- then use a script to convert it
>to proper XML for editing & formatting.
>
>
Again, you`re treating XML as "just another format". It seems to me that
a Wiki and XML (or at least validated XML, like Docbook) have
essentially opposite goals. In a Wiki, you keep conventions and
structure as simple as possible in order to encourage the free flow of
ideas. In XML, you`re more concerned with long-term maintainability, so
you specify the entire structure of the document in advance, and don`t
allow new text that doesn`t fit in with that structure.
I`m an XML true believer, but I`d never use it for informal writing or
brainstorming.
Joined: 05 Aug 2003
Posts: 21
Re: Docbook Editor
larry.kollar@... wrote:
>I`ve been converting a horribly messy Word doc to structured
>FrameMaker the last few weeks. I ended up using a handful of
>shell scripts (well, one was an awk script because it was a
>bit more complex) to wrap tags around selected pieces, then
>importing the XML into FrameMaker. It was *much* faster than
>wrapping text by hand.
>
>What Sebastian talked about is similar -- bang out a series
>of list items, then go back and pipe them through a script
>to add tags.
>
Except Sebastian is talking about authoring the original document, and
you`re talking about converting from an unstructured format. You
*expect* the latter to be complicated and done by somebody who`s
technicallly sophisticated. But hacking out a script for day-to-day
writing is less acceptable.
>The nice thing about *roff formatters is that the tags are
>generally so short that you can insert them on the fly without
>the mental pauses that many other formatting languages seem to
>require. A macro package like -mm expresses the structure well
>enough that converting to XML (and back) is possible; see ESR`s
>doclifter script for an example.
>
I`ve had this conversation before, only with LaTeX zealots. *All*
non-structured formats *support* two-way conversion. (LaTeX and TROFF do
it with macros, word processors do it with "styles".) That doesn`t mean
it`s *practical*. Writers, being mere carbon-based units, tend to break
structure rules: they forget, or they misunderstand a rule, or the rule
isn`t clearly stated, or they just can`t be bothered. The whole point of
using a structured format like Docbook is to prevent this noise from
creeping in. Treating Docbook XML as "just another format" and trying to
do maintenance in other formats defeats the purpose.
>
>This discussion suggests to me a two-stage approach: compose
>original text using very simple markup -- perhaps something
>similar to a Wiki language -- then use a script to convert it
>to proper XML for editing & formatting.
>
>
Again, you`re treating XML as "just another format". It seems to me that
a Wiki and XML (or at least validated XML, like Docbook) have
essentially opposite goals. In a Wiki, you keep conventions and
structure as simple as possible in order to encourage the free flow of
ideas. In XML, you`re more concerned with long-term maintainability, so
you specify the entire structure of the document in advance, and don`t
allow new text that doesn`t fit in with that structure.
I`m an XML true believer, but I`d never use it for informal writing or
brainstorming.
Joined: 05 Aug 2003
Posts: 4
Re: Docbook Editor
On Tue, 2003-08-05 at 16:49, Isaac Rabinovitch wrote:
> >
> Except Sebastian is talking about authoring the original document, and
> you`re talking about converting from an unstructured format. You
> *expect* the latter to be complicated and done by somebody who`s
> technicallly sophisticated. But hacking out a script for day-to-day
> writing is less acceptable.
I don`t really agree. There are different ways of writing. I can see
that if you employ a roomed of bored folks working my rote, you want to
establish practices. If you are an individual working solely on the
basis of end results, you have all sorts of different ways of working.
I author in (TEI) XML every day, for all my writing (except email :-}),
and I sometimes start with structure, sometimes with text. my documents
are often in invalid states while I ruminate and hack.
> The whole point of
> using a structured format like Docbook is to prevent this noise from
> creeping in.
so how come Docbook supporteds nonsense like "bridgehead"....
> In XML, you`re more concerned with long-term maintainability, so
> you specify the entire structure of the document in advance, and don`t
> allow new text that doesn`t fit in with that structure.
>
> I`m an XML true believer, but I`d never use it for informal writing or
> brainstorming.
you are missing out. your view of XML is perfectly OK and correct for
some circumstances. but it isnt the only use for XML!
Sebastian
Joined: 14 Jun 2003
Posts: 6
Re: Docbook Editor
At 10:55 05/08/2003 -0400, you wrote:
> >> = Sebastian Rahtz
> > = Isaac Rabinovitch
>
> >> ... what if I find it easier to edit my writing stuff which is
> >> temporarily invalid? for instance, I might write 6 list items quickly,
> >> then go back and top and tail them with a list tag.
> >
> > Well, I guess you have no problems with the
> > write-test-fiddle-test-fiddle-test... thing. But it would be
> > unacceptable in most organizations I`ve worked for. Too hard to train
> > new writers on the system.
>
>I`ve been converting a horribly messy Word doc to structured
>FrameMaker the last few weeks.
Mmm. Using upcast,
I converted a 2Meg document in 2 days.
Not to docbook, but to a fairly well structured DTD.
Hand crafting is rarely needed these days?
regards DaveP
Joined: 05 Aug 2003
Posts: 1
Re: Docbook Editor
On Tue, Aug 05, 2003 at 08:49:39AM -0700, Isaac Rabinovitch wrote:
>
> Again, you`re treating XML as "just another format". It seems to me that
> a Wiki and XML (or at least validated XML, like Docbook) have
> essentially opposite goals. In a Wiki, you keep conventions and
> structure as simple as possible in order to encourage the free flow of
> ideas. In XML, you`re more concerned with long-term maintainability, so
> you specify the entire structure of the document in advance, and don`t
> allow new text that doesn`t fit in with that structure.
>
> I`m an XML true believer, but I`d never use it for informal writing or
> brainstorming.
>
I completely agree with your distinction between "brainstorming" and
free flow on the one hand, and "long-term maintainability" on the other.
But isn`t that the point of the hack that Larry is talking about? I
personally find that tags and structure inhibits my flow of thinking, so
I write in a kind of smart text markup called ReStructruedText. I use
the parser for ReStructuredText to convert to XML, then use xsl to get
the XML in the right form. I`m sure everyone has their own hacks.
Paul
--
************************
*Paul Tremblay *
*phthenry@...*
************************
Joined: 05 Aug 2003
Posts: 21
Re: Docbook Editor
Sebastian Rahtz wrote:
>I don`t really agree. There are different ways of writing. I can see
>that if you employ a roomed of bored folks working my rote, you want to
>establish practices. If you are an individual working solely on the
>basis of end results, you have all sorts of different ways of working.
>
>
"Bored folks working by rote". Not a flattering picture of a tech
writing team, but I suspect it`s one many programmers have. And perhaps
a lot of badly-run teams actually fit that image. But a good tech
writing team requires a lot of intelligence and creativity. It`s hard
work to take a big mass of technical information, boil it down and
organize it so that it`s accessible to the people who need it. This is
work I find very challenging and stimulating.
At least the *writing* part is. There`s also the *process* part. Now, if
you work alone or with a couple other people, it might seem natural to
have a lot of ad hoc processes that you invent and implement when and
where you need them. Indeed, if you`re short of resources, there`s no
other way to get the job done.
But suppose you and a half-dozen others are struggling to maintain a
huge document base that needs drastic revision for each product cycle,
and the product cycle is measured in months, and the product history is
measure in years. Then your documentation process is something that can
easily get out of control. And that`s what happens when you don`t keep
a close eye on it. People invent new features faster than others can
learn to use them. Or they move on and nobody can understand how things
work. Or somebody at a key flow point invents something that makes sense
to them, and makes life difficult for everybody else, and nobody`s in a
position to tell them they can`t do that.
On my last job, the process was totally out of control. To the point
where 80% of my job was doing process crap and 20% was writing. OK,
there were problems that you don`t usually see (at least if you`re
lucky): company politics, long-term neglect of the tech writing
department, inability of key people to see that our writing tech was 10
years out of date...
Jeez, what was I thinking of when I took that job? But I digress...
Anyway, if you`re doing this kind of work (and, despite the trauma, it`s
work I love), you can`t let the process get out of control. And that
means watching out for unnecessary complications, cool features that
only make sense to the person who invented them, tools and procedures
that are only completely understood by one or two people... And in
particular, you need a way to edit your content that a new writer can
sit down and use without a lot of training. That`s why I`m a strong
believer in integrated validation. But perhaps I`m being too doctrinare
in insisting that this is the only way to compose Docbook content.
>
>you are missing out. your view of XML is perfectly OK and correct for
>some circumstances. but it isnt the only use for XML!
>
>
Well, perhaps if I`d spent my career in an environment that is more
friendly to markup languages in general, I`d be in the habit of using it
for every little thing, and have come to terms with all the necessary
tools. (The same way I have Vi`s obscure command set permanently
memorized.) But the sad fact is that I`ve spent most of my career in
Silicon Valley, where you have to fight tooth and nail to get markup
languages used at all. Never mind using XML for day to day word
processing, how do we persuade the boss to pause the Red Queen`s Race
long enough to change over to XML where it`s desperately needed?
Obviously my POV is colored by this situation.
Thing is, there are more people like me than like you. Fiddling with raw
XML is a concept that`s totally alien to 99% of all users. They do
everything with WYSIWYG editors: Word, Outlook, the usual suspects.
They`re not going to switch to XML, no matter how many clever AWK
scripts you show them. They *will* consider XML if it solves problems
that they have. And those problems are usually something like the ones
I`ve just described.
Joined: 06 Aug 2003
Posts: 4
Re: Docbook Editor
Isaac Rabinovitch wrote:
> "Bored folks working by rote". Not a flattering picture of a tech
> writing team, but I suspect it`s one many programmers have.
> And perhaps ... badly-run teams actually fit that image. But a good tech
> writing team requires a lot of intelligence and creativity. It`s hard
> work to take a big mass of technical information, boil it down and
> organize it so that it`s accessible to the people who need
> it. This is work I find very challenging and stimulating.
Agree 100%. Unfortunately, so few people have any idea what a tech writer
does or why it is so untrue that "everyone can write".
> At least the *writing* part is. There`s also the *process* part.
> Now, if you work alone or with a couple other people, it might seem
> natural to have a lot of ad hoc processes that you invent and implement
when and
> where you need them. Indeed, if you`re short of resources, there`s no
> other way to get the job done.
>
> But suppose you and a half-dozen others are struggling to maintain a
> huge document base that needs drastic revision for each
> product cycle...
Even as a sole writer I believe it is important to have reasonable processes
and a consistent approach so that someone can pick up the pieces if you move
on, or get hit by a bus, or whatever. Even if you don`t move on, why make a
rod for your own back from a maintenance point of view by letting things
slip just because you are the only one affected. And if you`re short of
resources, you really need strong processes to make the most of them.
> On my last job, the process was totally out of control. To the point
> where 80% of my job was doing process crap and 20% was writing. OK,
> there were problems that you don`t usually see (at least if you`re
> lucky): company politics, long-term neglect of the tech writing
> department, inability of key people to see that our writing
> tech was 10 years out of date...
In a true tech writer role I would expect to spend only about 30% of my time
actually writing. The other 70% would be a lot of business, system, and
audience analysis, interdepartmental liaising (politics included - and there
are few places of any size where you won`t encounter them), some internal
process stuff (a lot of this with a new team or where a new methodology is
being introduced), project management, usability testing, change management,
etc.
> And in particular, you need a way to edit your content that a new writer
can
> sit down and use without a lot of training.
As I said this is probably just as important in a sole writer situation
where you may not even have a hand-over.
> That`s why I`m a strong believer in integrated validation. But perhaps I`m
being too
> doctrinare in insisting that this is the only way to compose Docbook
content.
If you are talking about a tech writing team creating stuff, you can get
pretty much 100% compliance to any markup regime without constant validation
once the need is understood. In a team where we used HDK in conversion mode
to produce online help, strict adherence to function-oriented Word styles
was quickly established because if you didn`t use styles correctly your help
didn`t turn out right and we had a policy (because of time constraints)
where no post-processing was allowed. So much as XML is desirable from a
standards POV, structure and semantics is more a process thing than a
tool/language thing.
If you are talking about the general company population I have still not
found a tool that I could comfortably recommend from a usability point of
view - they are either too hard to learn and resistance is high, or they do
not produce content with enough structure/semantic information to be worth
the effort of changing the tools people are comfortable with.
> Fiddling with raw XML is a concept that`s totally alien to 99% of all
users...
> They *will* consider XML if it solves problems that they have. And those
problems
> are usually something like the ones I`ve just described.
Until we get some decent tools that are easier to use/implement, and that
generate some wider acceptance, I think a lot of people will still solve
these problems without using XML or will just bumble along with the huge
undifferentiated gobs of "content" the same as they have done for years.
After all, only a small percentage of companies actually employ *anyone*
from the information management professions.
-Melanie Kendell
Joined: 06 Aug 2003
Posts: 1
Re: Docbook Editor
On Tuesday 05 August 2003 15:55, larry.kollar@... wrote:
> I`ve been converting a horribly messy Word doc to structured
> FrameMaker the last few weeks.
A really ignorant question from one who only encounters Word
as a rather frightening alien phenomenon.
(I`m reminded of something I once heard the great E.M.Forster say --
"Nuclear weapons are not in my line. Unfortunately I seem to be in theirs.")
In any case, I thought I`d read somewhere that Bill Gates had had
a Damascene (?) conversion, and one could now output Word documents in XML.
Is that entirely a delusion on my part?
Or is it something that is going to happen when the state withers away?
--
Timothy Murphy
e-mail: tim@...
tel: +353-86-233 6090
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
Joined: 13 Jun 2003
Posts: 39
Re: Docbook Editor
>> I`ve been converting a horribly messy Word doc to structured
>> FrameMaker the last few weeks.
>
> Mmm. Using upcast,
Nice, and it supports MacOS X too....
http://www.infinity-loop.de/index.html
> I converted a 2Meg document in 2 days.
Heh. This one was a LOT bigger. *After* removing about 1/3 of
the content that wasn`t really needed, it came to 7MB (a bit
over 250 pages). The paragraphs were either section headings
or Normal + overrides.
Then throw in a screaming-tight deadline, having to back out
of a wrong version, graphics that had to be revised several
times, and large blocks of text that had to be completely
rewritten... this has truly been the Project From Hell. I`ll
have to feed it to the eval version of Upcast & see if it
would have made things a little easier. (Then again, wrapping
up text in XML was the *easy* part with this project... a
little easier is pretty much all I can hope for. :-)
> Not to docbook, but to a fairly well structured DTD.
>
> Hand crafting is rarely needed these days?
Much of this interesting discussion has been about using
plain text editors with appropriate plugins for creating &
authoring XML documents. I guess some people work better
that way.
--
Larry Kollar, Senior Technical Writer, ARRIS
"Content creators are the engine that drives
value in the information life cycle."
-- Barry Schaeffer, on XML-Doc
Joined: 05 Aug 2003
Posts: 4
Re: Docbook Editor
On Tue, 2003-08-05 at 23:01, Isaac Rabinovitch wrote:
> "Bored folks working by rote". Not a flattering picture of a tech
> writing team,
yes, sorry. purely my ignorance. I know nothing about professional tech
writers at all.
> But suppose you and a half-dozen others are struggling to maintain a
> huge document base that needs drastic revision for each product cycle,
> and the product cycle is measured in months, and the product history is
> measure in years. Then your documentation process is something that can
> easily get out of control.
maybe I am being naive, but surely the point of interest is the
marked-up text I check into the management system, not the way in which
I write the text? we all agree on the schema/dtd, and how every element
is used.
> cool features that
> only make sense to the person who invented them, tools and procedures
> that are only completely understood by one or two people.
sure. but there is room within that for people to get to the same point
by whatever route pleases them.
> .. And in
> particular, you need a way to edit your content that a new writer can
> sit down and use without a lot of training.
if i join your team, and say I want to do my text using vi under Linux,
and I produce the requisite quality (markup and content), who cares? the
person who takes it next doesn`t know or care how I created it
> Fiddling with raw
> XML is a concept that`s totally alien to 99% of all users. They do
> everything with WYSIWYG editors: Word, Outlook, the usual suspects.
> They`re not going to switch to XML, no matter how many clever AWK
> scripts you show them.
no. and their work will never have any archival value, and they`ll end
up redoing it very often, which will keep them and their descendants in
work for years. I certainly don`t believe this XML-centred view will
ever conquer the world.
--
Sebastian Rahtz Information Manager
Oxford University Computing Services
13 Banbury Road, Oxford OX2 6NN. Phone +44 1865 283431
Joined: 13 Jun 2003
Posts: 39
Re: Docbook Editor
> ... It`s hard
> work to take a big mass of technical information, boil it down and
> organize it so that it`s accessible to the people who need it. This is
> work I find very challenging and stimulating.
I agree with that. The good part is, learning to work in a
structured environment makes that part of the job easier, or
at least more intuitive. When you`re untangling a wad of
text that ties three separate ideas into knots, it`s helpful
to know what you want to do with those ideas once separated.
> But suppose you and a half-dozen others are struggling to maintain a
> huge document base that needs drastic revision for each product cycle,
> and the product cycle is measured in months, and the product history is
> measure in years. Then your documentation process is something that can
> easily get out of control. And that`s what happens when you don`t keep
> a close eye on it. People invent new features faster than others can
> learn to use them. Or they move on and nobody can understand how things
> work. Or somebody at a key flow point invents something that makes sense
> to them, and makes life difficult for everybody else, and nobody`s in a
> position to tell them they can`t do that.
Fortunately, there are already technical solutions to that
problem. First, tools like FrameMaker allow you to easily
remove overrides. Some writing groups take full advantage
of that feature; scripts can generate reports on overrides
and new paragraph/character formats, and then remove them.
XML is (or can be) even more strict in that regard, especially
if you have a DTD to validate against.
The second technical solution is source control. It provides
a record of who changed what, when they changed it, and a
way to back out changes. The bad news is that they`re not
suited for binary file types like FrameMaker or Word formats,
unless they`re designed for that purpose -- and then they`re
hideously expensive. The good news is that XML, being a plain
text format, *does* work well with source control systems.
Lacking either (or preferably both) technical solutions, one
must depend on peer pressure or other social strictures. We
all know how well *that* works. :-P
> Anyway, if you`re doing this kind of work (and, despite the trauma, it`s
> work I love), you can`t let the process get out of control. And that
> means watching out for unnecessary complications, cool features that
> only make sense to the person who invented them, tools and procedures
> that are only completely understood by one or two people... And in
> particular, you need a way to edit your content that a new writer can
> sit down and use without a lot of training.
Especially in a situation like you described above (very
large documentation suite developed over many years), I
would *hope* you wouldn`t hire a tech writer and expect
them to start maintaining that huge documentation base
"without a lot of training." Your example calls to mind
either aircraft or telephony products, gadgets that can
cause loss of life if they`re not working properly. Indeed,
I have an article tacked up outside my cube about how an
aircraft mechanic didn`t have a proper maintenance
procedure for the elevator controls & thus used pieces
of an installation procedure instead -- the plane crashed
two days later, killing 21 people. I have it to remind me
of my own responsibility and to point out what happens
when you gut a documentation department.
The point is, training is important -- especially if the
product is important enough to have a large, long-lived
documentation suite. Learning how to use some funky home-
grown tools that make the job easier is only a small part
of what a new writer needs to know before doing any major
work on that kind of documentation. Small wonder that so
many people think tech writers can be replaced by keyboard
monkeys....
> Thing is, there are more people like me than like you. Fiddling with raw
> XML is a concept that`s totally alien to 99% of all users. They do
> everything with WYSIWYG editors: Word, Outlook, the usual suspects.
> They`re not going to switch to XML, no matter how many clever AWK
> scripts you show them.
And these are exactly the people who are going to balk at
*any* kind of process requirements. They`re the ones who use
space runs instead of tabs, create Word documents that
consist solely of overrides to Normal, and can`t conceive
of making a Web page if they don`t have Dreamweaver. If you
show them how to use styles, they`ll glaze over and keep
doing what they`ve been doing. In short, they`re not going
to switch to XML, period.
> They *will* consider XML if it solves problems
> that they have. And those problems are usually something like the ones
> I`ve just described.
Sometimes you want a box-end wrench, sometimes you want
a ratchet... and sometimes you want The Persuader (i.e.
the 35cm adjustable wrench). Insisting on one tool that
does everything leads only to inefficiency, frustration,
and skinned knuckles. That`s where we are today, and we
wonder why we`re having so many problems -- some of our
problems we bring on ourselves. I said above that some
of the problems have technical solutions, but other
solutions are strictly social.
There are two ways to implement XML-based documentation
workflows today: assemble a toolbox or pay big $$$ to have
a consultant do it for you (and keep paying to maintain
it). Given the economy, there aren`t very many companies
that can afford to have someone else get their hands dirty
right now.
--
Larry Kollar, Senior Technical Writer, ARRIS
"Content creators are the engine that drives
value in the information life cycle."
-- Barry Schaeffer, on XML-Doc
Joined: 13 Jun 2003
Posts: 39
Re: Docbook Editor
> A really ignorant question from one who only encounters Word
> as a rather frightening alien phenomenon. [...]
> In any case, I thought I`d read somewhere that Bill Gates had had
> a Damascene (?) conversion, and one could now output Word documents in
XML.
> Is that entirely a delusion on my part?
> Or is it something that is going to happen when the state withers away?
It`s supposed to be in the next version of Office. Recently,
Microsoft has pulled back a bit and plans to include full
support only in the professional (i.e. more expensive) versions
of Word.
--
Larry Kollar, Senior Technical Writer, ARRIS
"Content creators are the engine that drives
value in the information life cycle."
-- Barry Schaeffer, on XML-Doc
All times are GMT
Page 1 of 3
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
Freelace Website Designer - Customer web design and software building.
China Wholesale - Electronics Products
Character Studio - Tutorials and Help
China Wholesale - Electronics Products
Character Studio - Tutorials and Help