Conference azur::mcc

4991.0. "How about great documentation for a great product!!!" by NEURON::BERBRICK (Bob Berbrick * Networks Instructor * Co. Springs) Mon May 03 1993 19:02

    
    A simple question (I hope!)...
    
    I am trying to put together comprehensive materials for the POLYCENTER
    classes I present and I seem to be having A LOT of trouble locating
    information in the documentation. 
    
    For example...
    
    When I go to register a NODE4 from the IM, using the Toolbox, the
    second Add Entity screen has you to enter the Synonym and the Address.
    These two fields are described in the documentation but what about the
    other fields, such as ACL and Text File? The Reference fields are
    pretty straight forward in what they are calling for but these two, in
    particular, I haven't got a clue what they are or what they are for.
    
    The POLYCENTER USE manaul point you to the specific AM USE manual for
    explanations of the fields but in there they only discuss the synonym
    and address fields... Where can I go to find out what ALL of the fields
    are for? It would seem to me that EVERY FIELD you can enter data into
    should be discussed in the manual... am I missing something here??
    
    *** Please look into the following suggestion ***
    
    I would also like to make a suggestion to the group responsible for
    writing the documentation. PLEASE...PLEASE...PLEASE... write for the
    network manager who must try to use what is written and actually sit
    down at a terminal, install the product, add their entities to the
    database, set up alarms and notifications, and actually manage their
    network. Much of the documentation would appear to be written more as a
    checklist of the available commands and how to performed from the IM 
    and the FCL; rather than a guide to setting up and using the product.
    Customers want to sit down and use a product, not days just
    trying to figure out how the documentation fits in to real 
    life. 
    
    Most folks setting up and using POLYCENTER know about their business
    and network. They do not always know that much about DEC products and
    how to use them. The documentation should lead them through the process
    from start to finish. Yes, I know POLYCENTER is a very complex product!
    Yes, I know the folks writing the product and documentation are short 
    of time, people, and dollars. Yes, I know all that but....
    
    Wouldn't it be possible to take a common situation or environment and
    build a detailed, step-by-step "cook book" of adding one each node4,
    osi, snmp, DEC and non-DEC bridge, ethernet station, circuit, and a
    node4 router; setting up the alarm rules with symbol substitution
    passing events, using scripts to monitor disk space, and
    notification, as appropriate, for each of these? One book; start at the
    front and go to the back, without having to reference five other
    manuals to figure out how to do something; covering all of the common
    operations in the order in which they should be performed. And BEFORE
    this document goes out the door, give it to junior network manager at a
    cutomers site to sit down and follow. If he/she can't make everything
    work, rewrite it until they can. Little mistakes in syntax may seem
    like minor problems but to someone setting up a network in POLYCENTER
    at night or on weekends (as that is the only time available to do it),
    having to debug documentation errors is infuriating, to say the least.  
    
    
    POLYCENTER is an **incredible** product... how about some incredible
    documentation to go with it!! 
     

    Hi Bob,
    
    I appreciate hearing the feedback on the documentation. We are working
    on making the documentation more task-based, and will look into
    implementing the suggestions that you mentioned. Your general
    suggestions reinforce our belief that we are working toward an
    appropriate goal (more task-based documentation), and your specific 
    suggestions help us focus on things that must be fixed. Both kinds of
    suggestions are helpful to the documentation team.
    
    Thanks,
    Ruth Callahan
    POLYCENTER Frameworks and Applications documentation project leader
    

    Please see Note 5006 in this conference.