Re: TECHWR-L Digest - 2 Dec 1993 to 3 Dec 1993

["Usability Expertise Center ph.603.881.2430" <raven -at- USABLE -dot- ENET -dot- DEC -dot- COM>]

Re:the postings from  Debra Carnegie (at Symbologic) and Steven Owens
(At Unidata) about  single-source user info:

        I think your effort is laudable, Debra, and it indicates that
you are helping to keep your company "au courant" in the '90s. I've
been on a few projects here at Digital Equipment Corp. Where we're
tried to do similar things--sort of. (Keep in mind that my experience
does not reflect Digital s a whole--I'm only one of 90 thousand
employees).
        We used something similar to sgml (sdml--an oxymoron which
means, I think, standard digital markup language, or maybe standard
document markup...). They key for was was making MODULAR CHUNKS OF
INFO that OTHER PEOPLE (e.g. marketing or Instructional design) could
call  into their documentation/course stuff. For example, Maybe I'd
write a list of "things this nifty tool can do for you"  and it would
sho (<-intentional typo for the typo tirade thread) up in my 7x9
perfect bound book in 10 pt. New York or something. A course developer
could grab that module and call it in (using <include> tags) to his
course materials, and it would become an overhead using 24 pt.
Helvetica or something. SGML and the various doctype definitions give
you lots power that way. (BTW__ the person doing the online help could
call it in to that, too.)

        To launch such an effort, you and your whole team needs to be
incredibly organized (which we weren't of course). For example, you
need to choose a specific style and stick to it no matter what (e.g.,
to recall other recent threads, are you going to use task-oriented or
procedure-oriented documentation, are you going to refer to the reader
as "user" or are you going to say "you" or are you going to say "Do
this, press that" without any pronoun..) we chose the imperative
voice--Press this, do that--in most situations (our audience is mainly
U.S. English speakers so we felt that was OK; a Japanese audience
probably would have felt that imperative voice was too strong, not
polite enough. We try to consider the culture of the majority of our
audiene--that's one issue that wasn't brought up in that thread about
You vs. the user or youser....)

        One downside is that the team (we had 4 writers, and one course
developer/instructional designer) ends up with hundreds upon hundreds
of modules--and to keep track of them we used a code management system
(the same one, in fact, that the engineers used for their code). You
have to make sure, for example, that nobody else is revising the same
module while you are, and all of that. That also means that to build a
book everybody has to check in all the modules that belong to that
book. (The sophisticated process we used for this was to run around
the office area screaming "Check in your doc modules now!! I'm doing
a build!! And then swear at the individuals who didn't...)

        !!!IMPORTANT!! In our situation, the key was not in the tools
we used (although sdml helped). It was in the PROCESS. We're a big
company. Marketing sat in ANOTHER STATE. We had to convince them that
they could make good use of info that we wrote--e.g. selectively pull
in decent modules of info that would serve their purposes. Then we had
to work together with them to let them know what we had written. There
was a CONSTANT need for COMPLETE COMMUNICATION with all members of the
info team--the writers, course devo, marketing, and the engineers. To
me, that was the hardest part, perhaps because of how big the company
is and how our groups are distributed.

So that's my more-than-2-cent's-worth. Every once in a while we toy
with the iead of writing a paper about it for an STC conference (Or
IEEE, or, something), but we haven't gotten around to it.

Regards,
Mary Beth Raven
Raven -at- usable -dot- enet -dot- dec -dot- com
Digital Equipment Coproration
Nashua, NH