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.
> In fact the more unstable the content, the more helpful single source
process
> will be. If content is stable it doesn't matter how complex the system,
you just
> get to work and start writing with the secure knowledge that you are
approaching
> the end of the work.
How? If content is in a constant state of flux, how would putting into a
single source system make life easier.
When content is messy, I think it is best to stick with the simplest
production methods possible. That way you can focus your energy on
wrangling the information. Once the information has settled down, then you
can start adding bells and whistles to the process. SS is one of those
bells and or whistles.
Now I am thinking about building new docs from nothing - not maintaining
existing ones.
> The less straight forward the more you can leverage single source and
data
> management systems as a cost effective solution to the creation and
maintenance
> of documentation. Unless you wish to make the claim that aircraft,
warships, or
> public transit systems are somehow "relatively straightforward
technologies ".
> Seems to me to be a rather strange twist in logic that a straight
forward
> technology would require a large doc set (see further on). I'm afraid
I'm not
> sure even the most complex of computer systems can match a warship in
terms of
> required documentation and they would still have a lot to measure up to
in the
> transport industry where we are producing multiple cross-referenced
manuals
> totaling tens of thousands of pages as well as interactive maintenance
and parts
> systems.
Its a question of stability, Eric. Many of these aircraft and warship
projects may have massive tons of documents - but the documents don't
change very much. Contrast this with software documentation that is
arguably smaller in quantity, but changes much more rapidly. In the three
years my company has written docs for one client, we've re-engineered the
docs 3 times because the products changed.
Some technologies or projects lend themselves to extreme order better than
others. This isn't some genius I have, its just common sense.
Thus, part of deciding whether you need a SS solution is determining
whether the circumstances warrants it. As many have pointed out, they
implemented smaller-scale time-saving measures that did the trick versus a
massive end-to-end SS solution.
> And I've seen horrendous hand built help systems and useless computer
> documentation that had no connection with a single source system that
shows
> these traits as well. Does that give me the right to pronounce upon and
judge
> the computer documentation industry as a whole? If the techwriting
industry was
> to be judged by some of the garbage out there I'd wonder if any of us
could find
> anyone to employ writers at all.
This is what bothers me too. Most publically available documentation, and
I mean 60% or more, is total crap. Useless, unintelligible drek unworthy
of space on a hard disk. I can only imagine what private stuff is like.
Why?
Well, as with all things, its a cocktail of issues. I think the core
problem of all bad docs comes down to content-ignorant writers and not
badly designed documentation processes.
> Proof and confession, from Andrew Plato himself, that he develops
processes and
> actually repurposes /reuses information through SS tools, and not cut
and paste,
> when appropriate.
Of course I do - never said I didn't.
> Andrew, were YOU avoiding YOUR real work when you designed that Access
> database? Because if this WAS part of your REAL JOB, then perhaps you
might
> understand, or admit, that many similar tasks (including single source,
template
> design, process development, and others) are indeed part of many
Techwhirlers
> real jobs and why some take offense to being belittled as a group by
posts with
> mocking titles and filled with hyperbole such as:
>
> <<And I yell "Things technical writers use to avoid their real jobs!">>
I make light of this because I find the incessant need for people to
"avoid their job" to be one of the most frustrating things about work.
They basically don't want to work - they want to TALK about work. They
want to leap ahead to the "interesting stuff" and brush past the "hard
stuff."
You can't build a warp drive until you've mastered walking. So, yes, I
have a certain sneer for those that want to shoot ahead and take on
responsibilities in tech writing when they haven't a clue what it is
they're documenting. SS, information mapping, etc. seem to always be
front-and-center in the topics that consume the work-shirking writers I've
met.
Remember, I never said SS is pure evil. I merely am offering a counter to
the "of course you need it" attitude that is prevalent out there. You
don't always need these things. There are plenty of smaller-scale
solutions, like Michele's conditional text solutions, that accomplish
essentially the same thing without any weird tools, methods, or cost.
This is why I pointed out my Access-Word solution. It was easy, quick, and
didn't cost my firm or my client an extra dime. Nobody had to research
anything, we didn't have to hold a meeting, and I wasn't dependent on some
freeware that may or may not be here tomorrow with support...We all had
Access, knew it well, and Word has built-in features to integrate the two.
Easy as it gets. Took one of my writers maybe a day to set the whole thing
up and maybe another day to teach the others on the team. Was it the most
elegant solution, no. But it worked. (We also then moved it over to HTML.)
This is one of millions of small scale "single-source" time savers out
there that are helping writers do their work better and not requiring a
lot of cost or complexity.
I understand that some people feel threatened and mocked by me - I am a
vocal opponent of something that they very firmly believe in. I feel the
same way when some derisive Penguinhead trys to tell me that these
WinNT-based security appliances we sell are crap. It hurts because I've
invested a lot of time (and money) into developing these appliances and I
think they're awesome. But, the fact is - they have weaknesses just like
anything (including Linux) else. And I don't always want to hear those
weaknesses.
In any event, don't take it personally. Its just tools and text and we're
disagreeing about stuff. Its not like I kicked your puppy or anything.
:-)
Andrew Plato
__________________________________________________
Do You Yahoo!?
Get email alerts & NEW webcam video instant messaging with Yahoo! Messenger http://im.yahoo.com
A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe. http://ieeepcs.org/2001/
+++ Miramo -- Database/XML publishing automation. See us at +++
+++ Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion +++
+++ More info: http://www.axialinfo.comhttp://www.miramo.com +++
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
