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:LONG: plea for help with planning project From:angelicatech -at- yahoo -dot- com To:techwr-l -at- lists -dot- raycomm -dot- com Date:Wed, 7 Jan 2004 15:12:45 -0700
I am a fairly long-time lurker on the list, who's coming out of hiding to
beg for some brainstorming help with a fairly major planning project I'm
undertaking. I have combed through the archives for relevant stuff, and I
recall some fairly recent discussions of XML/SGML that contined snippets
of useful information, but I'm after something I can't quite find.
I'd appreciate hearing from people about either my conceptualization of
the project, or my ideas about tools, or anything else I'm missing here.
The product is web-based course management software bundled with
a java core. We are (this is NOT ON MY WATCH) a relatively small
non-Microsoft shop -- in fact, there's a certain amount of gentle pressure
to move everyone from Windows to Linux. (Not so much on the docs
department, but you know how these things go . . .)
The current state of documentation is quite a sorry thing. We are a new
department, and I'm looking to manage things more efficiently, to produce
better deliverables, and to schedule things so that our behemoth corporate
parent can't sandbag us quite so easily. We have a variety of audiences:
"end-users" (instructors and students who use the software); users who
develop XML content for the app itself; project managers at various
corporate levels who need materials to sell new stuff to upper management;
developers all over (India, Australia, Russia, Texas . . .).
Most of what most of these people need doesn't really exist yet, or exists
only as relatively inaccessible poorly formatted flat content (impossible
to search, unindexed, etc.). There is "end-user" documentation, in the
form of the messiest, least valid HTML files I've ever seen (no, not HTML
Help, but HTML referenced directly from the interface, with some limited
context sensitivity, generated entirely manually), some almost as messy
print guides, FAQs (delivered online only, I *think*) and I'm still not
sure what else.
WHAT I'M THINKING OF DOING
Given the nature of the product and the shop, it makes sense to me to move
to managing docs (all of the above, plus everything else that pops up) in
XML. And yes, I'm thinking in terms of true single-sourcing. I'd really
like to chunk all content into a database (recommendations, anyone?), then
pull what's needed into XML (at what level I'm not sure, but I don't think
it matters at this point -- either output or deliverable), develop further
pieces of content as needed, generate output and deliverables, and away we
It seems so simple, when I explain it to developers and when I write it
like that. But given the single-sourcing discussions I've seen on the
list, the XML vs. SGML discussion (which is not specifically relevant
here), the tools wars, etc., I must be overlooking some big pitfalls. Any
words of warning, caution, experience -- as well as encouragement -- would
be greatly appreciated.
Also -- we need to revamp the Help completely. It isn't really any kind
of "system" at all at this point, just a collection of HTML files
referenced from the interface and sitting at the same level on the server.
One of the things that I like about my idea is that it has the potential
to be used to generate lots of Help variations, depending not only on
context but on usertype (and we seem to have usertype confusion, too -- so
I'm dreaming of some little app, written in I'm not sure what, that tracks
function use on the client side and pops up the right Help periodically).
We also need to generate a good TOC, index, glossary, browse sequences,
etc. None of which exist yet, at all. Like I said, it's vanilla HTML
files right now. (I won't torment you with naming conventions.)
THOUGHTS ABOUT TOOLS
Microsoft products are out, or anything that requires them. In docs at
our level (not corporate) we have wrested a couple of copies of Word only
(none of the rest of the suite) from the powers that be, simply b/c in the
World Outside People Ask for Word Docs. We ARE an OpenOffice shop, and
I'm gonna work on a training package to bring our OOo-resistant writers on
board (in my spare time . . . LOL). But OOo I don't believe that OOo by
itself has the capacity I need.
Frame seems like not quite the right thing, although I'm willing to be
persuaded otherwise. One dealbreaker with Frame MAY be Unicode support,
but I don't know enough about Unicode to know if UTF-8/16 is sufficient to
support other ISO standards (one of which we use, but I'm still trying to
find out which one).
XMetal is out b/c of the developer requirement for Visual Studio.NET (or
at a minimum Visual Basic). We would eventually want such capability, so
why start with what we can't continue with?
Arbortext's Epic is looking pretty good, with or without integrating
Documentum (without it we'll develop our own database -- there's a strong
propensity for growing our own tools here, which is kinda cool but not
always very efficient . . .)
Other XML editors/apps I'm missing here? I'm sure they're there . . . But
the Unicode support seems to be an issue with many of the lower-end ones
(Morphon, for example).
One tool issue I have NO ideas about -- whether or not we'll need
something separate for the online Help. My past experiences have been
with HTML Help generated by RoboHelp. I don't think we necessarily need
the tool, and don't know about other Help generation tools that integrate
with Arbortext, or if its HTML capabilities are sufficient if we design
carefully enough. (Even without the XML plan, I haven't been thinking in
terms of a specific Help tool.)
It is also possible that all we need is OOo and RoboHelp, and that all
this XML stuff is just getting carried away with doing things more like
the developers. But I see the potential for lots of cool stuff, and it's
so seductive . . . We also repurpose so much content already, but without
the capacity to rework it properly . . .
Any and all comments (I can take the flames if you need to throw them) are
MUCH appreciated. Questions for further reflection. Anything. Please cc
me as I'm on digest.
thanks to all in advance,
Lunar Logic, Inc.