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.
Subject:Re: Rant: Giving up on XML From:"elizabeth j allen" <eja -at- samurai -dot- com> To:siliconwriter -at- comcast -dot- net Date:Tue, 13 Mar 2007 11:11:59 -0400 (EDT)
Wow, that is quite the post, and I do really sense your frustration with
the whole process.
I have a different sort of take, and will use this to <ahem> somewhat
delinquently post the results of my own query into single-sourcing tools.
("single-sourcing tool," 5Jan2007)
As a result of my investigations, I too recommended that my team not make
the switch to XML. There is a steep learning curve and, in our case, the
fact that we do not localize our manuals pretty much killed off any reason
for converting to XML at this time.
The reasoning went as follows: implementing XML (in our case, a
DITA-flavour) requires a significant reworking of how we organize
information and think about our documentation requirements. We simply
cannot justify the time and expense of converting our documentation into
Tasks, Descriptions, and Reference chunks in order to properly store it in
a CMS.
Next up: Framemaker. I thought this was going to be the solution, but
further investigation revealed some significant problems. Primarily, it is
the WYSIWYG nature of the application that doomed it. In Frame, you show
and hide conditional text, creating a situation where a fellow writer may
open a file and delete text *without realizing he or she is deleting
hidden conditional text*. I can see where this could easily become a
problem with multiple writers working on the same document.
Oddly enough, in a previous job, Frame was the tool of choice. I prided
myself on my Frame user skills and found the program a joy to work with.
And it was, for the situation I was in at the time. I've also used
InDesign, PageMaker, Word, and QuarkXpress for documentation, all in
different situations. Whatever is the best tool for the job.
What did we do? We decided to remain with LaTeX. With the help of my
fellow tech writer, the "Guide to LaTeX, Fourth Edition" (Kopka & Daly),
some introductions to LaTeX on the 'net via Google, I produced my first
technical reference manual for an ASIC product in about 6 weeks. Mind you,
I didn't have to create the document definition file, which I suspect is
where you are running into difficulty.
I certainly appreciate your frustration and decision to return to Word as
an authoring tool. In my opinion, what often gets lost in the hype and
gloss of trumpeting new technologies is that sensibility that stops and
asks "What is truly needed to do this job?"
For example, do I really need MSProject for scheduling or can I just use
Excel? You'd be surprised at how many people choose the latter. And how
well it works.
In my case, I have absolutely fallen in love with LaTeX. I love the
control. I love the ease of reuse of chunks of information. I adore the
flexibility---I get to decide how my information is chunked. I get to
choose what's included and what's left out. I get to write complicated
boolean conditionals and use variables that allow me to leverage my work
across several chipsets. And the biggest plus? My source files are simply
text files, so I can work with whatever text editor I desire (currently
UltraEdit is the fave). And the text files show *all* the conditional
processing *all* of the time.
My files get checked into a content management system so my fellow
techwriter, who is hundreds of kilometers away, can work on the same doc
set simultaneously.
For me, getting to compile my finished documentation is a bonus. It
seriously bolsters my argument that tech pubs is an engineering function,
not simply a support role. I like coding my documents.
In short, I am having an absolute blast learning LaTeX and I hope I get to
keep using it for a while yet to come.
Does this mean I think you should use LaTeX as well? No, not at all. What
I would like to say to you is that you really shouldn't beat yourself up
for trying different tools and finding them lacking. Not all tools are
right for all situations. It's okay not to switch to XML. It's okay to not
use Frame. It's okay to realize that LaTeX is not ideal for your
situation.
You checked XML out and discovered some flaws, flaws that made it unusable
for you. Nothing wrong with that. In fact, there's a lot right with it.
Being aware of new technology and its limitations is a good thing. If
anything, I hope this experience doesn't completely dampen your
investigative spirit.
My name is Elizabeth and I don't use XML. :)
Cheers!
Elizabeth
--
Elizabeth J. Allen
Documentation Developer
"Make everything as simple as possible, but not simpler." -- Albert Einstein
siliconwriter -at- comcast -dot- net said:
> After weeks of research, reading and studying, I'm throwing in the towel
> on XML. I was really hoping I could use DocBook to turn the output of our
> code documentation software into a manual, but no such luck. The output
> from our software (Doxygen) is so idiosyncratic, so impossible to tweak,
> that I've been unable to change the page size from A4 to US letter. I
> tried using DocBook, only to find that the learning curve is steep,
> undocumented and tricky. Doxygen uses LaTeX as its output engine, and a
> creakier, more poorly documented, unnecessarily complicated piece of
> software I have never seen.
>
> So I'm actually going back to MS Word. There are not enough words in
> English to say how much I loathe and despise Word, but I can't justify
> spending weeks and weeks more trying to figure out how all the puzzle
> pieces of XML, DTDs, XLSTs and other alphabet soup fit together. I'm not
> interested in becoming a programmer in order to do my job, which is
> writing manuals, not coding stylesheets. My company already sprang for
> InDesign (which bombed big time), so I have no hope of persuading them to
> go to Framemaker, which I don't want to do anyway. So, it's back to Word.
> *head desk*
>
> Until now, I was an eager devotee of open source software. I was trying to
> move all our documentation into OpenOffice and other open source software.
> Now, not so much. I no longer trust open source, I find it extremely
> poorly documented from an end-user point of view, and it never, ever has
> all the features I need. The learning curve resembles a vertical wall.
>
> If any of you fellow tech writers who actually UNDERSTANDS XML ever gets
> around to documenting it so that technically savvy but non-programmer
> audiences can understand and/or use it, I will be very grateful.
>
> Thanks for listening.
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList
Now shipping: Help & Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help & Manual: http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
