Conference 7.286::digital

    I spent 2.5 years in hardware field service (I wasn't particularly good
    at it), 6 months doing marketing technical support, 18 months in
    manufacturing, and 6 years or so in programming. I'm now a hardware
    consulting engineer. I think some time in other groups is a very good
    idea. Perhaps not ten years worth, though. 

    I agree with Martin, but there doesn't seem to be any organized way to
    get the necessary experience, without risking your career by getting
    into something you have no skill for, and getting (correct) poor
    reviews.  I'd be willing to take a job elsewhere in the company if I
    thought there was a good chance I could get back if the fit wasn't
    good.
    
    (An aside: we aren't all at the level of Tom Eggers---he's been here
    forever and done everything, it seems like.  If the company was limited
    to people with Tom's qualifications, we'd produce 1/10th as much with
    1/1000th as many people.  I'm no Tom Eggers, and never will be.)
    
    Maybe I'm just too fearful.  Maybe I should do as Martin suggests, and
    take my chances.
    
    I think Martin is right about needing a broader perspective than just
    coding to function as a Principle Software Engineer.  Perhaps there
    should be more than one promotion path within Software Engineering: the
    other one would reward straight coding skills, but you'd never, never,
    be seen by a customer.  I might do well at that path (I've written some
    mean code in my younger days) but I wouldn't find it satisfying.  I
    left academia because, unless you're at the level of Don Knuth (even
    higher than Tom Eggers) nothing that you do ever benefits anybody.
    
    Here's an idea: take some vacation time, and spend it at a field office
    supporting a product you've just finished working on.  I'm just
    finishing DECforms, and haven't had much time for vacation in the last
    few years, so I've got a lot saved up.  Is there a field office who
    would like a DECforms expert "hanging around" this summer?  Please send
    mail---English-speaking only; I'm not good at languages, either.
    
    Does this seem bizarre, taking vacation time to do product support?
    Maybe so, but it's better than being confined to the ivory tower.
    
    I don't know if this would work in reverse.  It takes lots longer than
    2 weeks to do anything useful in central engineering.
        John Sauter 

    I like the idea of seeing how the other half lives.  I'm
    not willing to use vacation time, though.
    
    I agree that higher rank means "has to think about wider
    issues", and that higher pay means "does current job well".
    There's room for both.  The current system, where there is
    a maximum amount of pay for each rank might be construed
    as a limit on the red-hot coder.  Given that some upper ranks
    are not working as project leaders writing specs and scheduling
    field tests but rather as resident brains, this isn't really
    an issue.  I'd prefer not having offical limits.
    
    				-John Bishop

    This is an issue which has been discussed many times in the past.  The
    bottom line, if I remember correctly, is that the logistics (and
    expense) of rotating people to other locations/positions for short
    periods of time is very expensive.
    
    That said, though, I think that this could very well be critical to our
    success.  I'm currently in the Aerospace Engineering group doing work
    targeted for the Aerospace industry.  A minor problem is that I know
    virtually nothing about *how* that industry works.  Our field people
    almost certainly do.  If I went our for 3-4 weeks at a time to visit
    these different field offices, I could guarantee that I would have a
    better grasp of the customer's needs than if I spent 3X as much time
    reading technical journals.  It would probably be just as useful to
    have the SWS people come up here for a month or two to contribute their
    knowledge to the project.
    
    Jim

    Rotation would be useful in other situations as well.  For example,
    I'm a Principal SWE in a Manufacturing Engineering organization
    that's chartered to develop software tools to aid our own manufacturing
    plants.  It would be very benefitial to me and others in my group
    to be able to spend some time at a plant to really understand how
    the process works and the kinds of problems the people who work
    there every day face.  Yet we are actively discouraged from doing
    this.  The usual excuses are travel expenses and time constraints
    (this is never an item that shows up in project plans).
    
    I have never understood this, however, I think the light is dawning.
    We now have several people working offsite directly with our customers
    and the trend is increasing.  I think this is the right move, but
    in time, it might call into question the need for a centralized
    org such as ours.  The centralized/decentralized pendulum is still
    swinging with about a 5 year period and no sign of damping.
    
    Bruce

Re: .0

Your proposal makes a lot more sense to me now that you've said you're talking
about 2 weeks in these other jobs rather than a year.  I've actually written
a few specs and even dealt with some customers, mostly through the QAR system;
it isn't so bad if it can be mixed with some good solid coding/debugging.  I
don't think I ever want to be a full time spec writer or customer support
person, though.

What kinds of technical areas do you think a software engineer, say, should be
"rotated" through?

				-- Bob

re: .6:
> What kinds of technical areas do you think a software engineer, say, should be
> "rotated" through?

I'd like to see developers take customer phone calls.  Given the miracle
of modern technology, this wouldn't even require any travel expenses: just
tell Atlanta/Colorodo Springs that "between 8 and noon on Tuesdays, all
VMS support calls go to ..."  This will give ... a better understanding
of, if nothing else, where our documentation is unclear.

Central engineering people should also get involved in occasional pre-sales
calls.  This is (probably) done at the very big-bucks level, but it should
be done at all levels.  This gives the central engineering person an
understanding of the actual customer needs.  Hardware engineers should
go on field-service calls for their product.  (In both cases, they should
be accompanied by local-office folk.)

Although I'm recommending this for Principal/Consulting levels, it's
more important that junior people are directly exposed to customer needs.
This would, if nothing else, prevent ivory tower "not invented here"
and "See Figure 1" attitudes.

If the process hasn't changed in the last ten years, customer needs are
presented to local SWS, who pass them up the line to Corporate SWS, who
pass them to developers.  Notesfiles, by establishing peer-peer communication
across organizational and employment-level lines, act as a short-circuit
within the corporation.  Decus has traditionally been a short-circuit
between customers and developers. (is this still the case?)  Formal
short-term rotation acts as another.

There's an old joke among customers that they have to train their SWS
people.  I know that when I did DOS-11 and RSTS timesharing support,
my customers taught me about airplane flight testing, copper mine real-time
control, warehousing, car manufacturing, and freight-forwarding.  Similar
real-world knowledge is necessary if we are to build the products our
customers need.

Martin.

    re: .7
    
>There's an old joke among customers that they have to train their SWS
>people.
    
    Of course, the biggest joke is the incredible prices per hour we now
    charge so that _they_ can train _us_.  I have heard this "joke"
    for years; unfortunately, the customers no longer laugh when they
    say it.
    
    The worst part is that _very often_ the customer is training SWS
    people about _Digital_ products, as well as about the customer's needs.
    
    If nothing else, it would be good for SWS people to get a "View
    of the Future, According to Engineering".  Not some lifeless PID
    with all the "good stuff" squeezed out of it, but a chance to see
    what's being worked on, a chance to talk with the developers one
    on one, a chance to comprehend "the big picture" from an Engineering
    perspective, without some middle-man saying "you don't need to know"
    things that are common knowledge in Engineering.
    
    -- Russ

>> What kinds of technical areas do you think a software engineer, say, should be
>> "rotated" through?
>
>I'd like to see developers take customer phone calls.
    
    Pass.  I'd rather spend my time understanding how to do it right to
    begin with by understanding the customer's real needs than finding out
    why I didn't do it right because I didn't understand the customer's
    real needs.  Of course, having developers take customer phone calls
    might be a good way for developers to want to preemptively attack the
    problem of not addressing the customer's needs in the products we
    build  :)
    
    In a previous life I did what was stated in a previous reply: go and
    work on site for a customer.  We were an internal group, so our
    customers were other groups within DEC.  But the task to perform was to
    assemble engineering drawings of how to package up a product.  The
    drawings were already roughed out by an engineer and all I had to do
    was use a CAD system to make the drawings a reality.
    
    Didn't really learn all that much since I was fresh out of college and
    I was put at a correspondingly low level in the customer's
    organization.  But in following years, my exposure to manufacturing in
    general increased significantly and it really opened my eyes to that
    world.
    
    There's little doubt in my mind that the way to produce useful software
    is for the developer to understand the problem.  That's pretty
    axiomatic.  Going to the source is a good way to understand a problem.
    
John

    Like Martin I started out at DEC as a field SWS person. I think it
    was a valuable experience. Later when I joined my first engineering
    I found that this experience proved very valuable. I remembered years
    worth of customer wish list items that never made it to a formal SPR
    or DECUS meeting. My experience also made me very responsive to SPRs.
    SPR are an under prioritized item, in my opinion, in many organizations
    because engineers tend not to translate fixing SPRs as important when
    in fact to customers and to salespeople trying to get add on sales
    SPR responses are *very* important. A few months in a field office
    will teach that to someone in a way that nothing else can.

    I think that the customers that engineers visit have to be carefully
    picked though. Engineers have a tendency to be brisk. Especially when
    customers ask questions related to non-DEC h/w or S/w. Telling a
    customer that all ones problems are based on a third party disk, which
    I've seen/heard engineers use as an excuse to avoid working on a
    problem, is not a smooth move. In the long run though any engineer
    who can keep his mouth (mostly) closed and their ears open could really
    benefit a lot for a few months in the field.

    		Alfred

        I agree that, for the best results, Engineers should rotate
        through SWS and not the CSCs.  Otherwise, engineers will continue
        to have the wrong impression of customers.  :^)
        
        However, CSC experience could be valuable for both SWS and
        Engineering.  I, as a field Software Specialist, did a short stint
        in the Atlanta CSC and that was an education to say the least!!
        CSCs (now part of Field Service) are an entirely different
        world from 'the field' as SWS knows it.
        
        Ideally, I think those engineers who should/would work with
        customers should be on site as some type of short term resident.
        Working, day to day, in the customer's environment is the only
        way to get a good feel for the SOLUTIONS NEEDED FOR THEIR BUSINESS
        that our computers do or don't provide.
        
        By the way, there are a number of places in the corporation which
        provide the benefits and disadvantages of both worlds.  These
        places are known as ACES, which stands for Application Center for
        Engineering and Support and are part of SWS/E.  They do 'real'
        engineering efforts following the Phase Review Process and they do
        'SWS' efforts - custom software pieced together as quickly as
        possible to solve some business problem for a customer.  As
        Engineering, they develop and maintain software and present
        sessions and demonstrations at DECUS.  As Software Services, they
        visit customers, listen to their needs, offer their services to
        find business solutions and fight funding and resource battles. 
        
       _Mike
        
        P.S. I love it!  (SWS - 4 years, SWS/E - 8 months)

    I discussed the idea of of rotating to the field few years ago with my
    manager when I was in ACMS Engineering, but there wasn't (and still
    isn't) any of such programs, so I simply transferred to SWS in New York
    in '86.  Since then, I've learned not only about what Digital products 
    don't have, but also how insensitive I was as an engineer to field 
    issues.  

    Although I am in Sales Support now, I definitely agreed that engineers 
    should be rotated to customer projects, i.e. PSS, if possible.  That's 
    where I learned the 'serious' customer issues, such as what happened 
    during a crash of the production funds transfer system at a major money 
    center bank.  Sales Support may be right for those engineers who are
    interested in why their products aren't selling.

    One thing the engineers must keep in mind though.  Engineering IS
    the best working place in Digital.  The field (SWS specifically) is 
    probably the worst.  So, be ready!  (Maybe try something in the middle,
    such as COG.)

    Thomas

    P.S. - When I said engineer, I meant Software Engineer.  I don't know
    	   anything about HW Engineering.

    
    Good Topic!  I think it's a great idea to have the movement both
    ways.  As a sales support person I spend lots of time asking questions
    like 'why did engineering do that?', 'what does THIS TLA mean?'
    etc.  I would probably get a lot out of spending even a week in
    a development group.  By the same token, I think it's even more
    important for the engineers to get out to the field.  The people
    that are deciding on product content should be getting those needs
    from our customers.  
    
    We all have good thoughts but it's often too expensive for the company 
    to make these things a reality.  There are situations that come up
    however, that can make a trip to the field a reality for some people.
    At this very moment there is a person from the Atlanta CSC on
    a plane coming out to help me at a customer site for a month.
    My customer needed some DEC consulting and I couldn't find a 
    resource in the area with the right skills.  I called the CSC to
    get a few initial questions answered and I happened upon someone
    who had all the right skills.  I got the district managers
    talking and she's on her way.  The company motto is 'do what's right'
    and this was the right thing.

    It would be nice if there was some kind of database of people
    in the CSC's and engineering who would like an opportunity
    to come to the field.  Maybe something including name, position,
    skills, and length of time you could be available.  The worst
    deliveries (consulting) to fill are usually the short term ones.
    Just an idea.
    
    Donna
    
   

    re .8;
    
    I'd be glad to have some of the developers in our (SWS) office just for
    the chance to pick their brains as to where things are going. Back in
    my days as a customer, I could get this through DECUS meetings. Now
    that I'm on the "inside" I find myself treated like a suspected KGB
    agent. It would really be great to have the chance again to ask someone
    why the $%#^ they did it THAT way.
    
    -dave 

re: .15
    Now
    that I'm on the "inside" I find myself treated like a suspected KGB
    agent.

Umm, let's not forget that the field will sell anything they can get
their hands on.  If a developer wanders through a field office and
casually mentions the automatic coffee maker in VMS Version 6 DCL, you
can be sure that every customer in the known universe will want it
yesterday, even if VMS Version 6 isn't due out for two years.

There's a phenomenon in the personal computer industry known as "The
Osborne Effect" which is what happens to sales of existing products
when you prematurely announce a new product.  People stop buying the
old one; if the new one is late, the company goes belly-up fast.
(This happened to the first manufacturer of portable pc's.)

The PC software market gets around this by giving the first upgrade
as a freebie; but this is difficult to do with hardware.

Martin.

    It makes Expresso very fast.

I work for the US Area CSCs and on a number of occasions engineers have
come out for 1 or 2 week stints.  They don't necessarily have to take phone
calls.  They can spend time talking to folks, helping solve problems,
informal training, and listening in on phone calls.  Of course they are
welcome to take calls too.  In all the cases I'm familiar with it has been
of mutual benefit.  I agree that the CSC is not like the field and perhaps
a stint in both would be the best.  However, if you are a software or
hardware engineer and you want to know what customers think of your
product, how they use it, what problems/suggestions they encounter, etc. a
CSC (either Colorado Springs, Atlanta, or yes, Westboro, MA) is a good
place to start, due to the volume and diversity of calls.  Depending on the
situation, your skills, interest, and what product is involved, the CSC
might offer to pay expenses for your trip too (I'm not commiting this, but
it has happened many times).

- Jeff

    Trouble is, this kind of visit has to be fitted in when no urgent
    developement work is going on. SUch occasions are incresingly rare,
    but.. I agree on the priciple.
    
    A

    re: .19---How do I sign up?  (Please send mail, I don't want
    competition.)
    
    re: .20---I don't know of any project that's so urgent that somebody
    can't be spared for a week or two.  It might cause the project to slip,
    but no worse than being sick, or taking a vacation.  I like to think
    that I am a valuable employee, but I know that all work on my project
    won't stop just because I'm out.
        John Sauter

See Topic 765 for an opportunity for Engineering employees to take short-term
field assignments.

    Having seen this topic a bit late, I'd still like to add my two
    centimes.....
    The majority of replies seems to have come from SW folks (Eng, SWAS,
    FS...). However, the benefites clearly pointed out are also valid
    for HW design/support.
    I got the chance after 7 years of basic FS work to join CSS
    Engineering. By this many years ago, there wasn't any formal
    Maintainability engineering (CSSE). Nevertheless, trust me, my
    first project had lots of maintainability features.
    Having been away then for two years from the field, the next
    project still had lots of maintainability features, BUT gee
    when it came to install it at the customer's, (Engineering together
    with FS), we quickly found out the hard way that our I/O cable
    design didn't match anymore new corporate cabinet design.
    This is just a small example from a small engineering group.
    But I believe that it supports the principle of Field/Eng rotation.
    
    My today's job is (back in the Field) to get escalted customer problems
    fixed (CLD's and other). Engineering experience sure helps to
    understand why some things just can't be fixed in minutes/days..
    But I also see lots of cases where Engineering just doesn't understand
    what the real impact of such a problem is to the customer and his
    Digital subsidiary.
    On the other end, if Field resources had the means (sources, knowledge)
    of products, there wouldn't be so many CLD's required. Do you know
    of any better way to learn about a product than actually designing it ?
    Do you know anyone better suited to support a product than the one
    that designed it ?
    Sure it aint that simple with today's complex and huge products, nor
    with our huge DIGITAL, but it sure is worth trying to find a way
    for making Eng/Field rotation happen. It's easy to demonstrate that
    it costs $$$, the fact that most of the CLD's cost LOTS of $$$$ in
    problem-managerial overhead is not so evident to demonstrate, as this
    overhead is never really measured.
    I've talked to support as well as design engineers and besides a very few
    who really can't stand idea of a Project Management Process for the
    former or have no cummunications skills whatsoever for the latter, the
    majority would like to temporarily change roles.
    CSSE as linking the chain between the Field and Engineering should be
    able to iniate, implement, moderate... such programs. 
    I wouldn't believe that CSSE could be afraid in loosing their jobs
    doing so. I might loose mine as "Escalation Manager", but there are
    still other opportunities to be explored before retirement!
    Fred
     

    re: .2, .21
    
    Thanks to the author of .19 (Jeff Robbins) I was able to spend 2 1/2
    weeks of May working and teaching at the Colorado Springs CSC.  I took
    phone calls, as recommended by .7 (always under supervision).  I was
    also able to visit a local customer, though I didn't do any on-site
    work.
    
    My management initially wasn't enthusiastic about my doing this: I was
    able to get "permission" only if I agreed to take vacation and pay my
    own expenses.  As it turned out, the group I worked with in Colorado
    Springs offered to pick up my expenses (after I'd been there a few
    days) and after I returned my supervisor told me I could get comp time
    in exchange for the vacation.
    
    I got good reviews from the people I worked with, and I have pushed
    them up my management chain; I would like to get this rotation
    procedure institutionalized.  I recommend that others who feel as I do
    act as I did.  You may not be as lucky as I was (you may end up paying
    your own expenses) but if enough of us do it, with good results, it
    will be easier for the next guy.
    
    I not only got to push my idea, I also had a good time.  Anybody who
    visits Colorado Springs should check out Meadow Muffin.  Also, say
    hello to Jeff Robbins; I still think he has the best view in the
    building.
        John Sauter

    John,
    
    Having rolled in the floor while listening to a few of your DECUS talks
    a few years back, I can only imagine what customers must have felt like
    having you "on phones" at the CSC :-)
    
    I'll second the value of the experience.  A few years ago, I visited
    the CSC/CS to deliver a seminar on VAX BASIC V3.0 and I spent 2
    afternoons on phones to relieve specialists.  Those two afternoons gave
    me phenomenal insight into the kinds of problems CSC specialists deal
    with everyday (enough insight that I was very thankful to return to 
    the ivory tower of ZK).
    
    -Ken

    Hmmm.... You must have been at my EDT presentation in Miami, when the
    projector burned out and I had to retain the audience's attention while
    a new bulb was found.
    
    I spent nearly all of my telephone time listening rather than talking,
    since I was "under supervision".  Even though I did very little talking
    (to customers) I too learned a lot about the kinds of problems that the
    CSC specialists deal with, and I am happy to return to the ivory tower,
    also.
    
    However, there are lots of kinds of people at Digital (valueing
    differences).  Just because I didn't like it, and Ken didn't like it,
    doesn't mean it wouldn't be the perfect fit for someone else.  In my
    present job, my reward comes when I help to ship a product, which
    doesn't happen very often.  A specialist in the CSC gets his reward 5
    to 10 times a day, when he helps a customer with a problem.
    
    I urge the readers of this topic who think they might find a more
    fulfilling job at a CSC to check it out, if necessary the way I did.
    I know the VIA group is looking for qualified people, and I wouldn't be
    surprised if the other groups were looking, too.
        John Sauter

re: .26

John, could you tell us what you learned and what kind of insight it gave you
as far as future versions of your product are concerned or for that matter,
things in general that other product developers could find useful?

Bob

    I have a 350-line trip report which I will send to anyone who asks;
    I don't want to include it here because of its length.  To summarize:
    I became more sensitive to the need for supportability features, and
    I have added two such features to DECforms V1.1: better error reporting
    from CDD/Plus and better trace messages for data conversion.
    
    By visiting a customer site I learned what people are doing with
    graphics operator interfaces; I will be pushing for support for that
    level of capability in DECforms V2.0.
    
    An astonishing number of customer's problems can be solved by simply
    reading the manual.  Often the specialist will ask the customer to open
    the manual to a specific page, and then (very politely) tell him to
    read it.
    
    An overall impression: hardware will continue to drop in price, because
    of competition.  Software can't become too expensive, or people will
    steal it rather than pay for it.  The future source of margin is in
    the service part of our business.  As a software engineer I find that
    pretty scary, but I don't see any alternative.
        John Sauter

re: .28:
    An astonishing number of customer's problems can be solved by simply
    reading the manual.  Often the specialist will ask the customer to open
    the manual to a specific page, and then (very politely) tell him to
    read it.

One of the things I learned from my time in customer support (6 years) is
that "an astonishing number of customers' problems can be solved by simply"
writing manuals that can be understood by their audience.  This means
clear coherent writing, neither too much or too little, with reasonable
examples.

This is an extremely difficult task that requires competent writers,
enough time to get the job done correctly, good reviewers, and project
leaders who understand the problem and can communicate it to the writers
and developers.

One of my hot buttons in Dec is assuming that our inability to develop
understandable systems is somehow the problem of the user who can't
find the magic paragraph buried somewhere in 300 pounds of documentation
(I'm not suggesting that John Sauter is guilty of this.)

The best manual I ever saw in Dec was about 60 pages long and took
six months to produce.  That manual allowed me to bring a customer
up to speed on a complex product in two days with me staying about
3 pages ahead of the customer (it wasn't a system I normally supported).

Martin.

Martin,

Absolutely!  Right on -- and all those other positive-reinforcement kinds of
words.

I once wrote a (very small) manual and had it user-tested by a newly
hired secretary with no computer experience.  I asked her to let me know
as soon as she reached a point where she was stymied.  I then re-wrote
that part until she understood it.

It is my feeling that our manuals are only reviewed by 'experts' who don't
need the manual and/or the writers are getting paid by the word.

Incidentally, after general distribution (to about 100 Deccies) of my manual,
we discovered that it still wasn't read...


Betty

    re .30
    
    THAT is the best way to test something - give it to the non-initiated!
    
    Having done that a number of times, you will be amazed by what YOU
    (as a 'knowledgable professional') take for granted.
    
    The introduction to the Human Factors book, published by Digital
    Press, is a great example - it describes a novices experience with
    an electronic mail system for the first time.
    
    	-Barry-
    

    While I agree with Martin that our manuals could be better, even the
    best manual does no good if it is not read.  I don't know how to get
    customers to read manuals before asking an expert for help.  Perhaps
    it isn't possible.  
    
    On the other hand, perhaps it isn't necessary.  In one case that I
    observed, the specialist asked the customer to open a particular
    manual to a particular page, and pointed out some of the useful
    information to be found, information which related directly to the
    job that the customer was trying to do.  The customer seemed pleased to
    have this information readily available, as though it had been
    transmitted to him in written form by the specialist.  The customer
    had, by his own admission, never looked in this particular manual.
    
    Perhaps we should look upon our manuals as on-site resources which the
    specialist can refer the customer to, rather than as the primary (or
    only) source of information about the product.
        John Sauter

    Perhaps this is where online documentation will come into its own?
    
    - A

What about developing some VCR tapes?  That would be a more personal, shorter
approach to the basic instructions.  It could contain references to certain
parts of the written documentation for 'further study'.

Bet it would be a hit!!

Betty

Re: a couple back

Documentation? I spent 30 minutes on someone elses VAXstation trying to
work out how to change the colour of DECterm from blue on black to
something readable. Ended up giving in and using my VAXmate again.

My kids learnt how to change the colour of the desktop on a Apple MAC-II
without manuals. Maybe we should be aiming to make things that don't
need documentation... simplicity is quite an asset!
							- Ian W.

    I've run into several issues about our manuals that tend to
    intimidate customers into never reading them:
    
    - Unavailability (no one has seen the bloomin' thing for ages)
    - Lack of examples ("Syntax templates" can be confusing)
    - Cross Referencing and indexing lacks something
    - Frequent updates make manuals obsolete and are painful to manage.
    
    That said, Digital is still ahead of the curve in a lot of ways.
    Most of our traditional competitors had terrible documentation,
    and still do.  We even get tolerably close to IBM's standards.
    I've gotten favorable comments from a few former IBM-types, and
    even an IBM SSE who works with me on a current project has said
    that our documentation was very thorough.

    My own dream is that we develop a context-sensitive HYPERTEXT
    documentation system, to be the next evolutionary step above
    VMSHELP.  I know many customers who pretty much survive with
    online HELP without ever cracking the manuals.  The online
    HELP system in VMS is almost legendary within the computer
    business, and is a definite selling factor for VMS.
    
    Another dream is that we develop a method of easily FAXing stuff
    from support centers to customers.  So a specialist could extract
    info from various sources, cut and paste into a one or two page
    document, and e-mail/FAX it to the waiting customer.  Much faster
    than telling the customer what to type in line-by-line ...
    
    Now that it's a mark of shame for a business office *not* to have
    a FAX machine, it's time we start thinking of ways to use them.
    Marketing has already figured this out, and has started the VAX
    FAX ads, where a customer can dial 1-800-whatever and a rep will
    FAX out product sheets and so forth to them on short notice.

    Geoff Unland
    

    The FAX machine in Colorado Springs is used quite frequently to send
    information to customers.  It's all manual, though; it would be easier
    to use if it had a VAXmail interface.
        John Sauter

    I've already used FAX machines to communicate with customers on
    support issues.  ZKO now has its own FAX machine - previously I
    had to go to NUO a few miles away.
    
    			Steve

    Digital has it now! MRFAX came out a while ago I believe and allows you
    to send a FAX via Message Router.
    
    - Andy

  A few notes ago, someone mentioned "INdexing" as one of their bullets.
  I'd like to re-inforce that.

  The other day, one of my co-workers asked me about the $PUT service in
  VAX/VMS, looking for the main description of that service.  Now, I
  knew where to find it in that person's V4.4 DOCset, but rather than
  just tell this person, I suggested they look in the Master Index.

  No such luck.  All the references to $PUT were references to non-ob-
  vious places where it was mentioned, but the big reference was missing.
  So the problem of "familiarity breeds an assumption of understanding"
  applies to the people who select index entries as well as to the
  people writing the documentation in the first place.  (Probably one
  and the same people, in actuality.)

                                   Atlant

    Submitted a QAR? Moaning here will fix nowt.

    I would like sometimes to type "tell me more" after reading on line
    help. This command could invoke an appropriate piece of documentation
    via DECwindow book reader.

    One could also imagine "tell me more" or "explain" command that would
    expend on previously returned error message.

    Example :

    $notes decnetvax
    %notes-e-npexit , network partner exited 
    $explain
    VMS messages explanations
    Message "%notes-e-npexit , network partner exited " means that remote
    note server terminated logical link without explicitly specifying reason, 
    there are possibly some problems with the remote server .
    For further information, please contact system manager of the remote
    node.


    In other words, this facility could replace messages manual in many
    cases.

In a previous life I was a system wizard expected to know all the answers.  We
wizards never talked to end-users, but there was a user-support guy who did.
The support guy would then come to us with the question if he could not answer
it himself.  It was our policy never to answer the question directly, but to
point him at the manual that contained the answer, hoping that by osmosis or
something he would learn how, in the future, to look it up himself.

It didn't work.  He insisted that we tell him the answer directly each time.
We had to read to him out of the book.

John Sauter was one of my co-wizards.

    The "system wizard" experience that Paul is referring to in 752.43 took
    place in the early-to-mid 1970s.  I like to think that computer
    awareness in general has improved since then.  Perhaps the support guy
    that we dealt with is not now typical of users who ask for help from
    the "wizards".  Or perhaps the specialists in Colorado Springs are
    better at saying "read the manual" than Paul and I were.  In any case,
    I think things are better here and now than they were there and then.
        John Sauter

    
    well, while developing decnet for OS/2 to new Microsoft OS, we've
    come to learn and love a facility they have called quickhelp. It
    is online, infinitly better than the printed doc's (not hard to
    do i admit), contains references to releated subjects etc. From
    a code development perspective it has been great! If i could make
    myself comfortable with the "point and grunt" wimp style of interface,
    i might someday even have a clear desk! 
    
    just another example of while we're trying to get our act together,
    the small guys already are.

    <--(.45)
    
    Over three years ago PCSG began shipping [what I think was] DEC's first
    hypertext help system.  We called it "OUI":  Online User Information.
    It ran under MSWindows on the VAXmate, was very general and powerful,
    and had a lot of user-interface features that, I believe, still aren't
    available with Bookreader today.  It was a clear industry-leader at the
    time and probably still would be very competitive today with just the
    addition of graphics (Bob Fleischer might be able to comment on that).
    
    Alas, corporate politics were the death of it.
    
    						=maggie
          

My main concern about our documentation is:

	Not enough "FULL" examples,
	and too many half examples!

- Mike

    I'm sad to say that folks today aren't using the documentation any
    more than they did in the past.  If they have a question it's all
    too easy to ask the "wizards" using NOTES.
    
    				Steve

    I know this isn't really a "DEC documentation" note, but...

    o  I haven't read a DEC manual yet that couldn't be, on average, a
       third of its current size. And I don't mean smaller type on
       smaller pages :-) The last concise, thorough, and easy to follow
       (i.e., know where to look) DEC documentation I've seen is:

    	o  DOS/BATCH Handbook (circa 1974/5) - One phone-book sized manual.
           It never did explain satisfactorily what "F044" meant, though.
           "Omigod", I suspect.

        o  Terminals and peripherals handooks, 70's, before interface
           programming information was taken out and put into a _much
           longer_ manuals that shipped with the device.

        o  The RSTS BASIC-Plus summary appendix, the last BASIC documentation
           I ever saw that actually told you the order of the INSTR
           arguments without needing to deduce it from an unclear example.

    o  I get around the current VMS et al docsets because I've dealt with
       our documentation long enough to know where to look without needing
       and index. The indices often do not contain the obvious references,
       like "x - this is the main section on x". Too many index entries
       look like they were generated by the

           "noun/participle   [word found on] Page n-m"

    algorithm of indiscriminant index entry creation.


    It's been more than once that a customer has figured out which manual to
    read, searched it _cover to cover_ more than once and missed the
    information they were desperately looking for. This, from personal
    experience.

    A tome is not an effective substitute for throughness -- nor should it
    be mistaken for such.



    /Peters

re Note 752.46 by RAINBO::TARBET:

>                   -< The little guys aren't _always_ first! >-

        But Meg, doesn't this prove the point?  In the Digital scheme
        of things, PCSG was "the little guys".

        Bob

re Note 752.48 by QUARK::LIONEL:

>     I'm sad to say that folks today aren't using the documentation any
>     more than they did in the past.  If they have a question it's all
>     too easy to ask the "wizards" using NOTES.
  
        This is not necessarily bad.  Perhaps our expectation that
        people should find the documentation more satisfactory than
        an expert is wrong.  If we have developed a technology which
        allows novices, wherever they may be, to seek assistance from
        wizards, wherever they may be, is that not good?

        Bob

Re: .51

One problem is that our customers don't have access to the wizards via
NOTES, so if the documentation is unclear they have to talk to support
people, which costs money.  I think it's a problem in general that we have
so many convenient tools available internally that we don't see the
deficiencies in the products that are available to customers.

				-- Bob

    <--(.50)
    
    Bob, that's a depressing way of looking at it but you may well be
    right: it certainly _felt_ as tho we were the victims of an autoimmune
    response, didn't it!?
    
    						=meg

	It's kind of an adage among writers that users go through the
	following procedure when they have problems:

	1.  Experiment
	2.  Ask the guy in the next cube
	3.  Try online help
	4.  Ask the local expert
	5.  Ask the DEC expert
	6.  When all else fails, read the documentation

	Why this is so is not quite certain.  It may be explained simply
	by the traditionally poor quality of most tech writing.  Even if
	you're writing's quite good, a user who's been burned often enough
	won't even bother to find out whether it is or not.

	One way to get around this is to change the way you PRESENT your
	writing.  If you present it in the traditional way -- huge tome,
	encyclopedic organization, concept orientation, uninviting title
	page, no graphics or color, cluttered and unfriendly layout --
	the average user will avoid it like the plague.  Some things you
	can do to grab the reader's attention are to try different kinds 
	of docs (tutorials, quick reference), make the book a little 
	friendlier-looking, and try a different medium altogether (video, 
	ref cards, CBIs).  The first step is to get somebody to pick up 
	the book!

	The point about different media is an important one.  I think part 
	of the resistance to traditional documentation has to do with the
	medium itself -- i.e., paper.  Compared to, for example, online
	help, books have several disadvantages -- they involve task- and
	medium-switching, they can never be as context-sensitive, they
	can never be as fast, there's a physical separation between
	the task and the help ...

	So, my vote is for online stuff.  What I'm really interested in 
	is hypertext.  Now, I don't think this has to be something 
	incredibly complex.  You could, for example, have small task-
	oriented bits of information and then let the user fan out from
	there by presenting him with the same information in different
	forms: detailed explanation, conceptual or theoretical info,
	graphics, common problems or errors, exceptions to the rule,
	syntax, examples, related topics (which would take him right
	there).  I think it's important to combine this with features
	taken from the traditional technology of books: noting, book-
	marking, scroll bars, zooming TOC, etc.  I think you could take
	care of updating and distribution problems by putting it all on
	CDROM.

	Now if all that isn't sci-fi enough for you, my ultimate dream
	is to have the UI so "intuitively obvious" that there wouldn't
	be any need for documentation and all us tech writers (at least
	those of us who haven't gotten into UI) would be out of a job!

		-- Cliff

    One reason many users put the documentation last on their search list
    is the difficulty, in most shops, of locating a particular volume. 
    
    First you go to the book shelf only to find that the system manager has
    decided to relocate the "documentation library" to another area. 
    Having wandered around the building for a while, you locate the new
    site of the bookshelf to discover a) the 36-volume VMS doc set is
    totally out of sequence and b) the volem you need isn't there!  Your
    next task is to figure out who might have used it last and track him
    down.  However, you're lucky.  The fourth person you track down
    actually has volume 6c in her possession.  You return to your office,
    clustching your prize where you find that, for some whimsical reason,
    the subject you are looking for has been move to volume 7b!  Oh well..
    
    In general, unless the docs are cheap enough and small enough for
    everyone to have their own copy at their desk, they won't be used as a
    first-line reference.  The VMS v5 "General User's Manual" is a good
    start.  An "Advanced User's Manual" covering things like system
    services and RTL would be a dandy companion.  If each layered product
    could have a single trade paperback volume as its first-line reference,
    the documentation might be used a lot more frequently.
    
    -dave

>Note 752.54, SHALOT::ANDERSON 
>
>	It's kind of an adage among writers that users go through the
>	following procedure when they have problems:
>
>	1.  Experiment
>	2.  Ask the guy in the next cube
>	3.  Try online help
>	4.  Ask the local expert
>	5.  Ask the DEC expert
>	6.  When all else fails, read the documentation

100% True!  Writers themselves use the same procedure, so we should 
not be too surprised.  Three observations ...

Observation 1:
When I grab a manual, I want it to fall open to page X, where there is 
a boxed Note that says, "Hello, Marie, the information you want 
follows this note."  Anything less is frustrating.  Irrational, but true.

Observation 2:
A few months ago, when working on an indexing project, I asked 15 
people (all with more than 5 years at DEC) how many books they had 
read cover to cover.  Two people had committed this oddity:
     
     o a programmer new to the BLISS world skimmed and then read
       the entire BLISS doc set.

     o a writer new to code management (me) read the CMS User's Guide
       cover to cover, with highlighter in hand.  Lo! I came out of 
       the far side of the index understanding CMS.  The effort 
       crimped my work day, but the investment was worth it 10 times
       over. (Interestingly, I had already invested at least the same
       number of hours listening to incomprehensible explanations
       of CMS.)

       Now, I read coherent sections of manuals, but I haven't 
       swallowed an entire manual again.

Observation 3:
Hypertext and the aesthetic imperative

We could have hypertext right now, for ourselves and customers, if
we didn't have to wait for it to be pretty and structured.

I have "hypertext." Kinda, Sorta. I document a set of about 60 
applications.  After a year of EDIT/READing online files,
I *finally* made a SEARCH symbol that looks something like this:

  $ SEARCH BUNCH-A-PLACES:*.HLP,*.MAN,*.MEM,*.REF,*.TXT,*.NOT /WINDOW=3

The command gives me a 3-line chunk of text from N files, where the chunks 
usually contain enough info to answer my question, or at least point where to 
look for more.  The command output, tho, is not pretty. In fact, 
it can be downright ugly: asterisks! half sentences! isolated words!
table rows with no heads!  Some guru could probably code a crude 
hypertext that would make the output a bit prettier ... but it would 
not be as pretty, not as structured, as "real" hypertext.  

I think we have the know-how to do this officially, but our "aesthetic
imperative" (which we all have, just like the sex instinct and self
preservtion instinct) inhibits us from doing it for customers. 
(What would we call it? hyperpeep? hypersnatch? hyper-verite?)

Observation 4:
Hope more folks write to this note. A number of writers have been 
following it.  

    	Recently in the Low-end business, manufacturing hold what they call
    "boot camp" for the HW development group, and 5x5. The mfg team shows
    engineering their build process, etc. I was quite surprised how 
    LITTLE they really knew about the mfg process. Especially how the
    design of the product could be done to work WITH the mfg process,
    rather than make the mfg process "conform". 
    
    	I think an even more valuable way to "cross-train" would be to
    have engineering "man-the-phones" in Atlanta during a new product 
    intro. I think they might learn more hwat kinds of problems the field
    is faced with from day-to-day. One of our CSSE engineers wanted to get
    engineering to try it. But it never materialized. (project was
    cancelled) Perhaps the next time...
    
    Bob

    re: .57
    
    ``I think an even more valuable way to "cross-train" would be to
    have engineering "man-the-phones" in Atlanta during a new product 
    intro. I think they might learn more hwat kinds of problems the field
    is faced with from day-to-day. One of our CSSE engineers wanted to get
    engineering to try it. But it never materialized. (project was
    cancelled) Perhaps the next time...''
    
    This works, at least for Colorado Springs.  I don't see why it wouldn't
    work for Atlanta, too.  See replies 24 through 28 in this topic.
        John Sauter