| From: LINGO::WRIGHT "Rod Wright REO2-G/G9, 4064 28-Apr-1993 1038" 28-APR-1993 10:39:13.72
To: TNPUBS::GILLHAM
CC: WRIGHT
Subj: Action Plan for NCL task force
ACTION PLAN for NCL Task Force
Issued by: Rod Wright Date: 27-APR-1993
Task Force Members:
Rod Wright
Celia Marsh
Vickie Paulley
1 INTRODUCTION
The purpose of the taskforce is to develop the most effective method of
creating and delivering online help for NCL commands, in the most useful format
for the enduser.
2 SPECIFIC GOALS
The goal for the task force is ....
a. Define a format that will be used for online NCL help, for all products that
use NCL.
b. Agree with the NCL Registry a mechanism for ensuring that NCL help is stored
in the Registry, and that it matches the currently approved MSLs.
c. Secure agreement from the various development groups creating/amending MSLs
that they will use the above mechanism.
d. Develop a plan for getting the current NCL help into the Registry in the
correct format.
3 NON-GOALS
The non-goals for the NCL task force include:
We will not consider NCL documentation (reference manuals etc.).
4 DELIVERABLES/IMPLEMENTATION
Deliverables include:
A detailed document describing how to submit NCL help to the Registry.
Implementation is:
When writers liaise with project teams (developers and writers) and submit a joint request to the Registry
to register an MSL and its associated online help.
5 SCHEDULE
Milestone Start Date End Date
Submit Action Plan to Core Team April 1, 1993 April 1, 1993
Quarterly Status Report April 29 1993 -----
Agree NCL help style and layout May 05 1993
Quarterly Status Report July ?? 1993 July ?? 1993
Agree with Registry a method May 1993 July 1993
of tying online help to MSLs.
Secure agreement with
other development groups June 1993 September 1993
Create document outlining
help format, and process of
submitting it to Registry October 1993
Quarterly Status Report October ??1993 October ?? 1993
Agree process for converting
existing help to new format
and registering it. October 1993 November 1993
Present Taskforce Results December ??1993 December ?? 1993
|
| From: LINGO::WRIGHT "Rod Wright REO2-G/G9, 4064 06-May-1993 0955" 6-MAY-1993 09:58:16.91
To: NSTG::LYNCH,VICKIE,SEALS,BOB
CC: TNPUBS::SALUSSOLIA,MARVIN::COBB,WRIGHT
Subj: ncl help - getting it into the NCL Registry
Meeting with Bob Lynch of the NCL Registry, 05-MAY-1993
-------------------------------------------------------
Present: Bob Knowles
Bob Lynch
Celia Marsh
Vickie Paulley
Rod Wright
Purpose: To discuss how the Registry could be used to store NCL online help.
General Feasibility
-------------------
Bob Lynch supports the idea, and there are several options, so there's no
reason we can't do it.
However, to get the benefit of the exercise (which is mainly ensuring that the
ncl global section that ships with a product is accompanied by NCL help that
accurately reflects the global section), we need buy-in from all groups that
submit msls to the Registry.
We can proceed on our own, but unless other groups (especially DECnet) join the
scheme, the problems remain.
However, Bob Lynch, in his SQA role, may be in a position to make the logging
of NCL help in the Registry a condition for shipping a product.
Two Possible Schemes
--------------------
There are two possible ways to proceed: (1) the Correct Way, and (2) the Quick
and Dirty Way.
The Quick and Dirty Way
-----------------------
The Registry holds a master .hlp file for NCL help. When development groups
submit MSLs (either extensions or additions to the architecture), they should
also submit help text for the online help.
Development groups must provide an indication of where in the help hierarchy it
appears. Given the hierarchical structure of the .hlp file, this doesn't
present a problem.
The Registry could then edit this into the master .hlp file.
Pro's: We could set this up fairly instantaneously, without reworking the bulk
of the existing help text (ie that produced by DECnet). However, we
(layered products) would need to rework our files to put them in the
same format as DECnet.
Con's: Inflexibility of structure - to change the help format would mean a
complete rework of the .hlp file.
Registry workload: the Registry would be required to mess around with
.hlp files. Do they want to get involved with this?
The Correct Way
---------------
Currently the Registry stores the MSLs in a database. Each object (directive,
entity, characteristic attribute, event etc.) in the MSLs is assigned an
identifier.
This method proposes that the Registry create an associated text database to
contain the help text. Each item of help text would have a key consisting of a
string of identifiers. For example, the key for CREATE BRIDGE PORT would be
a.b.c where a is the id of the CREATE directive, b is the id of the BRIDGE
entity, and c is the id of the PORT child entity.
Development groups may be able to use the label form of the key, rather than
translating it into object ids.
Development groups would submit the text and associated keys to the Registry.
The Registry would use a search algorithm to structure the help according to
how we want it (we = all the development groups participating), effectively
creating the .hlp file for us to pick up when we pick up the global section.
Pro's: Flexibility - we can change the structure of the help just by changing
the search algorithm.
The Registry just has to store bits of text - it doesn't have to edit
them.
The help and the code are more intimately connected - could eventually
all be incorporated into the MSL.
Con's: Requires work to convert the existing help (mainly from DECnet) to new
format. (This work involves adding keys to the help text, and may not
prove too onerous.)
DECnet needs to agree to do this work. They could, in the short term,
just submit their .hlp file, but then layered products would have to
manually merge their help with DECnet's.
Could take some time to be fully operational - ie before all groups
participate.
What do we do about stuff that doesn't fit this scheme (like Examples),
or things that don't have an id (like the SHOW directive)? Bob said he
could create keys to take this into account.
Which Way?
----------
We agreed to pursue the Correct Way. We'll do some tests to highlight any areas
of difficulty.
Reservation
-----------
The major reservation (held mainly by me!) is how long it will take to be fully
implemented: there are many grumbles about NCL's suitability as an interface -
it would be nice to get the help scheme up and running before NCL goes away.
I don't think we should go this way unless we can be confident of getting most
development groups onboard within a fairly short time. I don't know yet what
'short' means.
Next Steps
----------
We're going to send Bob Lynch some help text, suitably indexed. This will be
for an MSL currently registered.
We'll index it using labels rather than number ids. A sample label would be:
SHOW | BRIDGE | PORT | DATA LINK ENTITY
Bob will then let us know whether he can work with this.
|
| From: NSTG::LYNCH 14-MAY-1993 18:41:38.75
To: @HELP.DIS
CC: LYNCH
Subj: PRgoress on the MTA On-Line-Help Program
**************** HOTE:::NOTE:::NOTE *******************
* The distribution list for this note has been composed of *
* folks whose email addresses appeared on recent correspondence *
* concerning ON-LINE HELP. *
* *
* The idea of using the DSSR Register to co-ordinate ON-LINE *
* HELP text with produt MSLs was first raised by Vickie Paulley *
* (REO) at a meeting with me in 1989, but support from other *
* groups was lacking. Since that time several attempts have been *
* made to get support from all tech pub groups to participate in *
* the program, but apparently the timing wasn't right. That seems*
* to have changed. *
* *
* Earlier this year a proposal was borught forward by Rod Wright *
* (REO) and at a meeting held in REO earlier this month we agreed*
* to develop and test a procedure for registering on-line help *
* text for all entities in the DSSR databsse, and to develop *
* output formats for both on-line access to the help text and *
* to create .HELP file generations from the DSSR REGISTER data *
* base. The test program is in progress. A set of help text for *
* on entity MTA AGENT has been supplied by Vickie Paulley and the*
* text is now being added to the DSSR Register data base. Out put*
* in TEST form will be generated within a week or so *
******************************************************************
Subj: MTA Agent Help FIle example
Vickie, this structure provieds a good idea of how to view the
example text you sent for MTA AGENT. We are in the process of loading
the data base with that text. Stan Lund has completed an extension of
the data files to accomodate the text and has modified the interfaces
so that the text can be readily inserted. We are anticipatig having
the text in some output for for you folks to look at by the end of
next week provided that there are no problems.
Yesterday we had a review of the process we are using to crete output
and were concerned about the structure that you would like to see.
Your memo gives us what you are loking for and will make our output
match this structure.
Interestingly we have had an inquiry from DECmcc about on-line HELP,
and they are now included on the distribution list of interested doc
folks. IF you know of more folks who would be interested in this
project, send the email addresses along to be added to the
distribution list.
Will let you know by mid week where we are.
Regards,
Bob
-------------------------------------------------------------------
From: FORTY2::PAULLEY "Vickie Paulley REO2 F/G2 ext. 4641" 14-MAY-1993 07:53:22.96
To: nstg::lynch
CC: ian,martin,bob,lingo::wright,PAULLEY
Subj: Hierarchy for the MTA AGENT entity
Bob,
I am not sure how you wanted us to present the hierarchy information
to you, but if you are unhappy with what I have provided let me know.
This example hierarchy is to be used against the files that we
supplied at the end of last week. Note that we have included levels in
the hierarchy that for the moment we have not supplied text for.
Typically these are for the MTA entity that appears above the AGENT
entity in the tree.
Vickie
Using the MTA AGENT example:
At level 1: MODULE
At level 2: MTA
At level 3: MTA AGENT
At level 1: SET
At level 2: SET MTA
At level 3: SET MTA AGENT
At level 4: SET MTA AGENT ARCHIVE
At level 4: SET MTA AGENT INVOCATION FILENAME
At level 4: SET MTA AGENT PASSWORD
At Level 1: EVENTS
At Level 2: EVENTS MTA
At Level 2: EVENTS MTA AGENT
At Level 4: EVENTS MTA AGENT ARCHIVED FAILED
At level 1: SHOW
At level 2: SHOW MTA
At level 3: SHOW MTA AGENT
At level 4: SHOW MTA AGENT ARCHIVE
At level 4: SHOW MTA AGENT INVOCATION FILENAME
At level 4: SHOW MTA AGENT MPDUS OUT
At level 4: SHOW MTA AGENT MPDUS IN
At level 4: SHOW MTA AGENT FAILED ARCHIVES
At level 4: SHOW MTA AGENT STATE
At level 4: SHOW MTA AGENT UID
At level 4: SHOW MTA AGENT TYPE
At level 1: DELETE
At level 2: DELETE MTA
At level 3: DELETE MTA AGENT
At level 1: CREATE
At level 2: CREATE MTA
At level 3: CREATE MTA AGENT
At level 1: ENABLE
At level 2: ENABLE MTA
At level 3: ENABLE MTA AGENT
At level 1: DISABLE
At level 2: DISABLE MTA
At level 3: DISABLE MTA AGENT
|