| T.R | Title | User | Personal
Name | Date | Lines |
|---|
| 18.1 | Action Plan | TNPUBS::GOVONI | | Fri Aug 20 1993 17:02 | 88 |
| ACTION PLAN
for Release Notes Task Force
Issued by:
Bob Govoni March 29, 1991
Task Force Members:
Bob Govoni
Mariellen Sheridan
Larry Holmes
Marsha Kinnear
Jill Callander
1 INTRODUCTION
The members of this task force know from experience that product release notes
are inconsistent in content and format. Since it is a common practice to
write release notes as a last minute task, the overall quality of the document
suffers.
Often, release notes are one of the first, if not the first, documents read
by the customer. This creates a poor first impression of the product.
2 SPECIFIC GOALS
The goals for the task force are:
o Define the purpose, scope, and goal of release notes
o Define the purpose, scope, and goal of cover letters and customer
letters, as they relate to release notes.
o Identify the information that belongs in release notes.
o Provide guidelines for writing release notes. These guidelines
will include a recommended process for creating release notes.
o Have a least one pilot to test these guidelines and procedures.
3 NON-GOALS
The non-goals for the release notes task force include:
o We will not provide a template.
o We will not recommend which tools to use to write release notes.
4 DELIVERABLES/IMPLEMENTATION
Deliverables include:
o A detailed document describing the content of release notes, as well as
the process for producing release notes.
o A sample of release notes, cover letter, and customer letter.
o Results (or post mortem) of the test pilot.
Implementation is:
o Distributing these guidelines and performing at least one pilot.
5 SCHEDULE
Milestone Start Date End Date
Cover Letter Guidelines:
General Review June 1993 June 1993
Finalized June 1993 June 1993
Release Notes Guidelines:
General Review August 1993 August 1993
Pilot August 1993 October 1993
Finalize October 1993 October 1993
|
| 18.2 | Minutes - March 19, 1993 | TNPUBS::GOVONI | | Fri Aug 27 1993 11:07 | 284 |
| Release Notes Task Force Minutes
March 19, 1993 - Kickoff meeting
Attendees: Mariellen Sheridan
Larry Holmes
Marsha Kinnear
Bob Govoni
For this first meeting, we went around the table to get everyone's impression
of what we want this task force to accomplish. Afterwards, we discussed
various issues with release notes.
Definition:
We need to create a definition of release notes. After this minutes,
is an attachment from the 073 standard about release notes and cover letters.
Goals/Process:
o Create a set of guidelines that describe:
- Content of release notes. What should and should not be in release
notes.
- Process for creating release notes (how and when you write them).
- Format of release notes.
o The guidlines will assume that the release notes writer could be a
technical writer or an engineer.
o Recommend the presentation of release notes, for example, hardcopy
and online (ascii and postscript files).
o Discuss authoring tools.
o Offer limitations on release notes, such as:
The information in the field test release notes should either be
fixed or incorporated in the documentation and not be in the final
release notes.
o Explain the reasons for using these guidelines, such as:
- This is one of the first documents a customer sees, and, therefore,
gives the customer a first impression of the product.
- In a customer survey done by the IPA II quality task force, customers
want to see a list of new features in release notes (for new revisions
of a product), and they want the release notes printed and shipped with
the product.
- For Alpha products, engineering must justify release notes over 20
pages. (Diane Florio supplied this information after the meeting.)
o Clearly explain which product groups would benifit from using these
guidlines. (Larry pointed out that the hardware group might not
realize that these guidlines apply to them too.)
Several times the point was made that release notes end up being a "dumping
ground" for miscellaneous information. It is often formatted badly and
contains unnecessary information, which could be confusing to a customer.
We also discussed if this task force was serving a valid and useful purpose
for T&N Pubs and the engineering community in general. The response was a
resounding yes for all the reasons listed above. In addition, two engineers
have given their support.
A DECmcc engineer, Jill Callandar, has agreed to join the task force but
could not make the kickoff meeting.
Marsha Kinnear talked to another engineer who cannot join because of
her schedule but has agreed to review our material. The following is part
of a mail message to Marsha from this engineer, which describes her opinion
of why release notes look bad:
1. she feels the wrong people write them. it has been her experience
that they assign an engineer who does not have good communication skills
and have him/her write them. (this could be worded a bit more
diplomatically).
2. they are always written too late. (in her last group, the product mgr.
bugged everyone to start writing the release notes in advance, the writers
helped and they improved dramatically.)
Action Items:
Bob - Fill in the IPA action plan and pass it before the team next week.
(Everyone else finished their action items during or right after the meeting!!!)
From the latest DEC standard 073 (from Bookreader, thanks Marsha!). Note
the similarity in purpose for release notes and cover letters.
2.1.3 Release Notes
Release notes describe new or changed product features,
bug fixes, restrictions, known problems, and workarounds.
Publications groups can provide online release notes, printed
release notes, or both. Online release notes, however, are
encouraged to ensure that all users have access to the
information.
The following specifications apply to printed release notes:
Binding Method: Ring binders (See Table 3-2 for sheet
capacity of binders.)
If bound separately:
2 through 13 text sheets: corner stapling
4 through 56 text sheets: saddle stitching
4 through 195 text sheets: white wire-O
56 through 500 text sheets: perfect binding
Trim sizes: 8-1/2 x 11 inches, 7 x 9 inches, A4, and
A5
Text stock: 50-pound, white, opaque
Drilling: Ring-bound release notes are drilled.
Saddle-stitched, corner-stapled, and
perfect-bound release notes may be drilled
to allow the customer to put the manual in
a ring binder after shipment. Wire-O bound
release notes cannot be drilled.
Internal dividers: Nontabbed dividers may be used.
Nontabbed divider Same as text paper used in manual
stock:
Covers: Corner-stapled release notes have no
covers.
Nontabbed front and back covers are used
for saddle-stitched, perfect-bound, or
wire-O bound release notes.
Tabbed front covers can be used for ring-
bound release notes and must be used if
there are multiple manuals within the ring
binder.
Optional graphics allowed. (See
Figures 3-6 to 3-23 for layouts.)
Cover stock: 10-point, Bristol/Cover, white, coated one
side
2.5 SPDs, Cover Letters, and Customer Letters
Documentation kits may also contain SPDs, cover letters,
and customer letters.
In general, customer letters are rarely used in
documentation kits. Rather, cover letters are used to convey
important technical changes, restrictions, workarounds, and
getting started information.
2.5.1 SPDs
SPDs are legal documents describing the important
functional characteristics of licensed Digital software
products. Text is printed on both sides of the sheet.
The following specifications apply to SPDs:
Binding method: 2 through 13 text sheets: corner stapling
4 through 56 text sheets: saddle stitching
Trim sizes: 8-1/2 x 11 inches and A4
Stock: 50-pound, white, opaque
Drilling: None
Ink: Black
2.5.2 Cover Letters
Cover letters may be customer surveys, preinstallation
information or errata sheets, and so on. Cover letters must
contain a part number and a copyright statement on the
first page. The copyright statement must comply with one
of the following options, depending on the availability of the
copyright symbol:
When the � symbol is available, use:
� Digital Equipment Corporation.
YYYY. All Rights Reserved.
When the � symbol is not available, use:
Copyright (c) Digital Equipment
Corporation. YYYY. All Rights Reserved.
For cover letters:
� Text is printed on one or two sides of the sheet.
� A cover letter is not printed on Digital letterhead.
� No signature is printed.
The following specifications apply to cover letters:
Binding method: 2 through 13 text sheets: corner stapling
Trim sizes: 8-1/2 x 11 inches, 7 x 9 inches, A4, and
A5
Stock: 50-pound, white, opaque
Drilling: None
Ink: Black
2.5.3 Customer Letters
A customer letter is a formal correspondence that carries
a facsimile signature printed on Digital letterhead with
the DIGITAL logo. Refer to the Company Identity Manual
for technical specifications and for layout information.
Customer letters must not contain any information that
would normally be protected by a copyright. Text is printed
on one side only. For software kits, offset printing or
xerographic printing is used, not matte thermography.
The print supplier will print the letterhead logo and facility
address for major facilities. Your local Purchasing group
can verify whether or not the supplier stocks letterhead for
a facility.
If the print supplier has letterhead for the facility issuing
the customer letter, the publications group must submit
repro for the text of the letter and the facsimile signature.
The author's name may be typed or written. The
publications group must know the letterhead layout for
the appropriate size letter so that the text will be positioned
properly.
If the supplier does not have letterhead for the facility, the
publications group must type the letter on the appropriate
letterhead, supply the DIGITAL logo on an overlay,
and mark up for color printing in accordance with the
Company Identity Manual specifications.
The following specifications apply to customer letters:
Binding method: 2 through 13 text sheets: corner stapling
Trim sizes: 8-1/2 x 11 inches, 7 x 9 inches, A4, and
A5
Stock: 24-pound, 25 percent cotton fiber writing,
bright white
Ink: DIGITAL logo: PMS 307 (blue)
Facility location: Black
Text: Black
Signature: Black (Use a black felt-tip pen.)
Drilling: None
|
| 18.3 | Minutes - March 26, 1993 | TNPUBS::GOVONI | | Fri Aug 27 1993 11:07 | 84 |
| Release Notes Task Force Minutes
March 26, 1993 - 2nd meeting
Attendees: Mariellen Sheridan
Larry Holmes
Marsha Kinnear
Bob Govoni
Jill Callander
Action Plan:
We discussed goals and other items related to the action plan. The 1st
draft of the action plan was sent to the team the Monday after this meeting.
Some decisions made include:
o Need to have doc supervisors and project leaders send our finished
guidelines to the LOB managers. This is one way to ensure that the
guidelines are distributed to everyone. In addition, we will need
high-level backing to ensure that the guidelines are followed.
o We need to define the intended audience for release notes.
o Because there is an overlap in definitions of release notes and
cover letters, we need to define both.
o Cover letters and customers letters are two separate entities, yet
they are often confused. Therefore, we also need to define customer
letters.
Definition of Cover Letters:
Cover letters contain the following types of information:
o Legal information
For example, the cover letter would explain any incompatibility issues
with other products as of this release.
o Explanation of unusual circumstances.
For example, the documentation produict titles are different than the
product name. (Normally, documentation does not need to be listed
in the cover letter.)
o Provide a pointer to critical information contained in the release notes.
In this case, the pointer is to critical information that affects the
user's ability to use the product. Again, this is information in the
release notes. The information should not be repeated in the cover
letter.
o How to print release note (provide the file name).
o The cover letter begins with "Dear Customer."
The cover letter should be the same size as the documentation (for example,
7x9 or 8.5x11).
We also discussed the format of cover letters (date, copyright, part number)
and should there be a standard closing statement.
We determined that customer letters are letters to one or more specific
customers, as defined in DEC Standard 073.
Action Items:
o Bob to send out action plan for team review (done on 3/29).
o Larry and Bob to interview release engineers and SSB people to test our
definition of cover letters.
o Everyone to bring in sample cover letters.
Next Meeting:
Friday, April 2, at 2:30 in Holmes (LKG1-3 in diagonal corner of building
from the cafeteria.
|
| 18.4 | Minutes - April 16, 1993 | TNPUBS::GOVONI | | Fri Aug 27 1993 11:08 | 68 |
| Release Notes Task Force Minutes
April 16, 1993 - 3rd meeting
Attendees: Larry Holmes
Marsha Kinnear
Bob Govoni
Jill Callander
Cover Letter Guidelines:
We discussed input to the cover letter guidelines from Joe O'Connor and
agreed to the additions. Bob also interviewed two other release engineers
(Dadeen and Joni Silveria). They liked the guidelines and had no
additional input. However, they did state that SSB has no requirements
on the content of cover letters and that cover letters themselves were
not a mandatory requirement.
We determined that we need to create a cover letter package, containing
the guidelines and sample cover letters (preferably one software and
one firmware). Initially, the team will review this package, then the
package needs to be reviewed by T&N Pubs personnel (especially editors) and
an engineering manager from each organization supported by T&N Pubs (i.e.,
NMS, IBM, DECnet, Hardware, terminal servers, etc.) Jill volunteered
her manager, Anne Pelagatti.
We also discussed creating a sample cover letter in DOCUMENT, which could be
used as a template. We did not reach a consensus on this.
**ACTION** - Bob to create a generic software cover letter as a sample and
update the guidelines, then put the package together.
Release Notes:
We discussed printed release notes. We believe as a team that cover letters
might not be necessary for if the release notes are printed and shipped.
Information normally contained in a cover letter could be covered in the
release notes.
We discussed a process for developing the release notes guidelines:
1. Brainstorm and write up all the obvious do's and don'ts. This will
take two meetings: one to brainstorm, the 2nd to objectively review the
list from the first meeting.
2. Research the list by looking at existing release notes from all major
supported technical areas (i.e., NMS, IBM, DECnet, Hardware, terminal
servers, etc.)
We discussed the reasons for brainstorming before the research. Briefly,
the overall feeling is that we have the experience necessary to list all
the obvious requirements for release notes, such as do not duplicate
information in the documentation, list last minute technical changes not
in the documentation, etc. We these requirements written down, we
can research the existing release notes for more specific and detailed
requirements.
3. Interview internal engineers and managers and have the list reviewed.
4. Interview external customers. This will be coordinated with other IPA
groups that may also be interviewing customers.
Next Meeting:
Friday, April 23, at 2:30 in Holmes. The agenda is to brainstorm!
|
| 18.5 | Minutes - April 30, 1993 | TNPUBS::GOVONI | | Fri Aug 27 1993 11:08 | 43 |
| Release Notes Task Force Minutes
April 30, 1993
Attendees: Jill Callander
Bob Govoni
Marsha Kinnear
o The attendees reviewed and edited the sample cover letter. Bob will
incorporate the edits and submit the cover letter to editing.
o Bob reported that he searched through the DEC standards and could not find
any standard for release notes. The inability to find any DEC standard
for release notes led to the question -- Should we submit our guidelines
(when complete) to the DEC standard committee?
o There was a general discussion regarding the level of detail that we
should include in the guidelines. The consensus was that the guidelines
should not be detailed. Also, Jill suggested we include a list of books
that would aid the "non-English" major when writing the release
notes. For example, O'Rourke's Writing for the Reader.
------- --- --- ------
Action Items:
o Bob - Revise and send the cover letter guidelines to the release notes
team and the TNPUBS editors.
o FOR ALL - Prepare to create a list of release notes requirements
at the next meeting.
o FOR ALL - Decide on whether we should distribute the cover letter to
the entire publications group for comments next.
Next Meeting:
Holmes Conference Room
May 7, 1993
2:30 p.m.
|
| 18.6 | Minutes - May 7, 1993 | TNPUBS::GOVONI | | Fri Aug 27 1993 11:09 | 71 |
| Release Notes Task Force Minutes
May 7, 1993
Attendees: Larry Holmes
Marsha Kinnear
Bob Govoni
Cynthia Day (new member)
Cover Letter Guidelines:
There was some confusion about customer letters vs cover letters.
Customer letters are addressed to one or more specific customers, where
cover letters are addressed to all customers. This definition needs
to be added to the guidelines.
The guidelines have been sent to the T&N Pubs editors. Comments from them
are expected well before the next meeting.
We discussed how product managers and other project team members will
be made aware of the cover letter and release notes guidelines. Cynthia
suggested that a summary paragraph of each of the two guidelines be placed
in the documentation plan. We will bring up this discussion again once
the guidelines have been completed.
Release Notes:
Cynthia brought in an excerpt from the Digital Technical Requirements
Reference Guide. This excerpt contained a checklist for release notes.
Using this excerpt and some brainstorming, we came up with the following
list of release notes requirements:
o "Golden Rule:" The release notes do not contain information that is
documented elsewhere.
o Release notes can contain problem fixes or problems resolved by the
product.
o Release notes can contain known problems or restrictions.
o Release notes can contain document changes or omissions
o Release notes can identify changes from the last release (new features),
if not documented elsewhere.
o Release notes can contain problem reporting procedures, if not documented
elsewhere.
We then discussed some points about the structure of release notes:
o There should be a "purpose of release notes" paragraph.
o There should be a Table of Contents, if necessary.
o If there is no Table of Contents, add a bulleted list of topics in the
purpose paragraph.
Marsha showed us such a structure in the MSU release notes.
**ACTION ITEM** Marsha will be bringing in copies of release notes with
known good structures for our analysis.
Next Meeting:
Friday, May 21, at 2:30 in Holmes.
There will not be a meeting on May 14 due to Bob and Jill moving to TAY2.
|
| 18.7 | Minutes - May 21, 1993 | TNPUBS::GOVONI | | Fri Aug 27 1993 11:09 | 57 |
| Minutes from the Release Notes Task Force
-----------------------------------------
Date: 5/21/93
Attendees: Bob Govoni, Marsha Kinnear, Cynthia Day, Larry Holmes
Discussions:
-----------
1.Worked on Task Force schedule of deliverables
A. Cover letter guidelines - schedule to start
and end effort during the month of June (see table).
B. Release notes guidelines - schedule to have reviews and
final information available by October 93 (see table).
**SCHEDULE**
------------------------------------------------------------------------------
Guidelines Dates Comments
------------------------------------------------------------------------------
Cover letter start 6/1 Bob G. to incorporate new comments
end 6/30 complete guidelines by end of June
Release notes start 6/1
general review 8/15-30 List of reviewers TBD
Pilot 7/1-10/1 Need volunteer to test guidelines on
a real product sometime within this
timeframe
final 10/1/93 complete guidelines in October
------------------------------------------------------------------------------
2.Discussed license letters guidelines
A. It was decided that this task force will not address license letters
i. If time at the end of current goals, we may revisit this idea
3.Discussed cover letters
A.Reviewed comments from editors group
i. Reviewed each comment and decided validity/usability of comments
ii. Bob G. to update guidelines with valid comments
ACTION ITEMS
------------
1. Cynthia to bring an example of problem reporting to next meeting
2. Cynthia to find out if SPR's are included in all software kits
3. Cynthia to bring a copy of SPR to next meeting
4. Cynthia to bring a copy of technical requirements summary list to next
meeting
5. Cynthia to bring example of VAX DOCUMENT CLETTER doctype to next meeting
6. Bob to update guidelines
|
| 18.8 | Minutes - June 10, 1993 | TNPUBS::GOVONI | | Fri Aug 27 1993 11:09 | 99 |
| Release Notes Task Force Minutes
June 10, 1993
Attendees: Larry Holmes
Marsha Kinnear
Bob Govoni
Cynthia Day
Jill Callander
Cover Letter Guidelines:
The cover letter guidelines are nearly ready for review. We created
the following list of product managers, engineering managers, and others
to review these guidelines:
Rick Pratts (TOOK::PRATTS)
Elizabeth Hawes
Vickie Prescott
Linda Armstrong Bradley (DELNI::LAB)
Bill Gassman (SKIBUM::GASSMAN)
Deb Flint (DELNI::FLINT)
John Forino (TOOK::FORINO)
Brad Kennedy
Mark Collett
George Neilsen (DELNI::G_NEILSEN)
Mike Bouchard (DELNI::BOUCHARD)
Carol Noones (TNPUBS::NOONES)
Gail Ferreira (DELNI::FERREIRA)
Laura Sargent (MOLAR::SARGENT)
Deb Curtis (MOLAR::CURTIS)
Andy Shores (DELNI::SHORES)
John Lewandoski (MEMIT::LEWANDOSKI)
ACTION: Jill will verify and fill in the E-mail addresses.
Cynthia brought in a copy of the SPR form and verified that this form
does ship with all software products. However, the SPR form does not
contain customer service phone numbers. The team feels confident that
support phone numbers are made available to those customers that by
support services.
The team questioned whether or not the SPR form ships on CDROM for those
customers who by software on CDROM only.
ACTION: Cynthia will determine if the SPR form is available on CDROM.
If the SPR form is available on CDROM, we will delete the reference to
problem reporting procedures from the guidelines; otherwise, the reference
will remain.
Cynthia showed the team the format of a cover letter when using DOCUMENT's
CLETTER doctype design. The team agreed with the format and agreed that
the guidelines should reference this doctype.
Larry suggested that we should use a checklist format for the guidelines
for ease of use. The team agreed and further suggested that we should
try to fit the guidelines on two pages.
ACTION: Larry will work on streamlining the guidelines.
The team discussed how the guidelines can be enforced. Basically, they
can't. However, Cynthia suggested that a subset of the guidelines be placed
in the documentation plan. Everyone agreed. The team needs to discuss at
a later time how to incorporate these guidelines into the docplan
template.
Release Notes:
Cynthia fulfilled her action items from the last meeting by bringing in copies
of the two Technical Requirements Guide: one for PCs, one for OpenVMS, ULTRIX,
OSF, and SUN.
We discussed who should be interviewed for the release notes guidelines.
We created this partial list:
Internal: CSC, John Levy, Customer Service.
External: Fermilabs, Dow Chemical, overseas customers
The team also realized that internal and external customers for each
product area might need to be approached differently. For example,
Cynthia could include release note questions on a survey that she will
be sending to her product customers; Jill could ask her customers these
same questions when she calls her customers on other matters.
We all agreed that we need to create a questionnaire and that the questions
should take no more than 10 minutes to answer. We considered the possibility
of trying out these questions on internal customers before contacting
external customers.
Next Meeting:
Thursday, June 17, at 2:30 in Brown in TAY2-2.
Agenda: work on the release notes questionnaire and add to the existing
list of internal and external customers to interview.
|
| 18.9 | Minutes - July 8, 1993 | TNPUBS::GOVONI | | Fri Aug 27 1993 11:13 | 52 |
| Release Notes Task Force Minutes
July 8, 1993
Attendees: Bob Govoni
Larry Holmes
Marsha Kinnear
o Larry distributed the cover letter guidelines that he reviewed. The
task force members agreed to add information regarding DEC standard
204. DEC standard 204 includes information about ECO and MUPs guide-
lines. The cover letter will be sent out for review.
o We reviewed the release notes questionnaire.
o Phil Milgrom submitted a list of suggestions that he received from customers
regarding what the customer would like to see in release notes. The
suggestions are:
- Detailed list of all new features
- Cross-references to the manual sections describing these features
- List of new features introduced for each previous version (for
people who skipped versions)
- A list of bug fixes for each version
Action Items:
o All task force members will come up with a list of internal and external
customers (preferably a minimum of three names from each member) that
will receive the release notes questionnaire.
Plans for Next Meeting:
o We will collect data and develop release notes guidelines.
Next Meeting:
Brown Conference Room
TAY2-2
July 12, 1993
2:30 p.m.
|
| 18.10 | Minutes - July 15, 1993 | TNPUBS::GOVONI | | Fri Aug 27 1993 11:14 | 90 |
| Release Notes Task Force Minutes
July 15, 1993
Attendees: Larry Holmes
Bob Govoni
Jill Callander
Cover Letter Guidelines:
The cover letter guidelines need minor tweaks and will be ready for review.
Bob will add a bullet to state that problem reporting procedures should not
be included in cover letters.
Larry added two more names to the review list. The review list consists of
product managers, engineer managers, and others who we feel can provide
valuable input to these guidelines.
We agreed that the review should be until July 31. At that time, Bob will
send a reminder to the review list.
The cover letter guidelines are now a background process. We will gather
input, then we plan to send it out to the T&N Pubs group for a final review.
ACTION: Bob to send out guidelines to review.
(Bob sent them out the next day.)
Release Notes:
We need to ensure diversity among the customers we interview to accomodate
the following issues:
o Needs of large vs small companies. In particular, is the person using the
release notes a software specialist or an end user.
o Operating system used, such as OpenVMS, ULTRIX, UNIX, MS-DOS.
Jill discovered that U**X users might require that release notes be
available as man pages. PC users might expect release notes to be called
README files.
ACTION: Jill to research other U**X products to see if release notes are
currently available as man pages.
o Needs of national vs international customers.
To ensure appropriate diversity, we need to coordinate the list of customers
interviewed.
ACTION: Every team member needs to send Bob a list of customers that we plan
to interview. Bob will maintain the list and the team will evaluate it for
diversity.
We discussed the process of gathering information from customers. Each
team member needs to provide following:
o A brief description (a few lines) of each company interviewed and its
environment. This must include if the user is a software specialist or
an end user.
o Interview at least 3 customers either directly (phone or personal
interview) or indirectly (paper questionnaire or through a reliable
internal contact). Note: If you have trouble finding 3 contacts, Bob
and Jill know a few local customer support people.
Jill has already chosen 3 diverse customers: Dow, Bank of Boston (has an
international network manager), and TEC.
ACTION: Bob needs get a GM customer contact from Anne Pelagatti (Jill's
supervisor). GM is a UNIX shop.
Jill discussed the problems with man pages, including inconsistencies in
format and approach. Is this a problem that the IPA should research?
ACTION: Bob to talk to IPA representative about having IPA research use of
man pages.
Next Meeting:
No meeting next week!
The next meeting is Thursday, July 29, at 2:30 in Brown in TAY2-2.
Agenda: work on the format, not content, of the release notes guidelines.
bob
|
| 18.11 | Minutes - Aug. 19, 1993 | TNPUBS::GOVONI | | Fri Aug 27 1993 11:14 | 23 |
| From: TNPUBS::GOVONI "To boldly write what no one has written before! 227-3268 20-Aug-1993 1603" 20-AUG-1993 16:09:27.27
To: @RL_NOTES.LST
CC: GOVONI
Subj: Release Notes Meeting Minutes - 8/19
Hi,
This was an abbreviated meeting due to project schedules and meeting
conflicts. Cynthia and I discussed format issues for the release notes
on her DEChub project, which will be going out next week.
Perhaps the most interesting item was that the DEChub release notes are
shipped online and as hard copy, and the printed release notes are more up
to date than the online. In a recent customer interview, the customer
wanted to see release notes online, since they would be more up to date than
printed release notes. As a task force, we might need to address this
in our guidelines.
NEXT MEETING:
Thursday, Aug. 26 in the Brown conference room located in TAY2-2
bob
|
| 18.12 | Minutes - Sept. 2, 1993 | TNPUBS::GOVONI | | Fri Sep 03 1993 13:55 | 106 |
| Release Notes Task Force Minutes
Sept. 2, 1993
Attendees: Mariellen Sheridan
Bob Govoni
Jill Callander
Marsha Kinnear
Cover Letter Guidelines:
There has been no response from the product managers to the review of the
cover letter guidelines. We decided to release it to T&N Pubs as is
(after Mariellen gives it a review). When we send the release notes
guidelines for review, we will also attach the cover letter guidelines, so
there will be a 2nd pass.
Pubs Quarterly Meeting:
The IPA Core representative asked if we would be willing to present at this
meeting. The presentation would include the cover letter guidelines and
the process that we're following to create the release notes guidelines.
The team like the idea, but no one present was able to volunteer. Bob
will ask the absent members if they would like to volunteer.
** After the meeting, I talked to Bruce Gillham, who noted that we should
send the cover letter guidelines to the IPA core team for approval before
presenting them at the group meeting. I sent Bruce the guidelines.**
Release Notes:
Jill discussed her man pages action items. Basically, release notes are
not normally released as man pages in the U*IX environment. However,
the release notes are available in a format similiar to readme.txt files.
Also, the release notes tend to be in ASCII format.
The team also discussed the release notes content. We came up with the
following:
Release Notes Contents
One- or two-line description of product.
1. Installation Notes
- High level overview of installation process, if appropriate.
- Warnings and gotchas in the installation process, which should be
included in the overview if present.
- Changes to the installation manual.
2. Important technical/process changes
- Mostly those changes NOT in the documentation
- If appropriate, include important technical gotchas that could
affect other products, whether or not they are in the documentation.
3. Other changes/bugs not in the documentation, and documentation errors.
Other Notes:
- The release notes should reference the documentation for information
and details instead of including that information.
- Customers do like to see documented the new features of each release.
This should be documented in a place other than the release notes.
(NOTE: This information is useful to end users who do not necessarily
have access to the release notes.)
Ongoing Action Items:
ACTION: Every team member needs to send Bob a list of customers that we plan
to interview. Bob will maintain the list and the team will evaluate it for
diversity.
ACTION: Bob needs get a GM customer contact from Anne Pelagatti (Jill's
supervisor). GM is a UNIX shop.
ACTION: Bob to talk to IPA representative about having IPA research use of
man pages. **DONE**
Next Meeting:
I will be on vacation Sept. 7-15. We do have the Brown conference room
(TAY2-2) reserved at 2:30. Feel free to set up a meeting! The
distribution list is:
tnpubs::govoni !chairperson
took::callander
TNPUBS::CDAY
tnpubs::d_florio !interest list
tnpubs::l_holmes
tnpubs::kinnear
tnpubs::m_quinn !IPA sponsor
tnpubs::sheridan
|
| 18.13 | Minutes - Sept. 23, 1993 | TNPUBS::GOVONI | | Thu Sep 23 1993 18:18 | 72 |
| Release Notes Task Force Minutes
Sept. 23, 1993
Attendees: Larry Holmes
Bob Govoni
Marsha Kinnear
This meeting was devoted to discussing the cover letter guideline comments
from Chris Billington via the IPA core team.
We discussed each of Chris's comments and agreed to the following changes:
o Modify the cover letter definition for clarity and to add definitions
for ECO and MUP letters.
o Rewrite the first three bullets under the Guidelines section for a
positive approach.
o Mention the CLETTER DOCUMENT doc type.
o Change the guidelines around the header, IMPORTANT TECHNICAL INFORMATION.
o Clarify the wording about copyrights.
o Add a bullet about pre-installation information.
o Remove greeting and ending bullets.
In addition, the team agreed to the following:
o Look at producing cover letter templates.
o Recheck the various DEC standards and the Technical Requirements Guide.
o Contact Chris for clarification on some comments, especially around TIMA.
Action Items:
ACTION: Bob to contact IPA core to determine the procedure to finalize the
cover letter guidelines.
ACTION: Every team member needs to send Bob a list of customers that we plan
to interview. Bob will maintain the list and the team will evaluate it for
diversity.
ACTION: Bob needs get a GM customer contact from Anne Pelagatti (Jill's
supervisor). GM is a UNIX shop.
ACTION: Bob to talk to IPA representative about having IPA research use of
man pages. **DONE**
Next Meeting:
I will be on vacation Sept. 7-15. We do have the Brown conference room
(TAY2-2) reserved at 2:30. Feel free to set up a meeting! The
distribution list is:
tnpubs::govoni !chairperson
took::callander
TNPUBS::CDAY
tnpubs::d_florio !interest list
tnpubs::l_holmes
tnpubs::kinnear
tnpubs::m_quinn !IPA sponsor
tnpubs::sheridan
|
| 18.14 | Minutes - Sept. 30, 1993 | TNPUBS::GOVONI | | Fri Oct 01 1993 11:30 | 48 |
| Release Notes Task Force Minutes
Sept. 30, 1993
Attendees: Mariellen Sheridan
Bob Govoni
This meeting was devoted to finishing the cover letter guidelines.
We made the following changes to the cover letter guidelines:
o Rewrote first sentence for cover letter definition for clarity.
o Deleted the sentence under the definition of release notes that states
the release notes guidelines will be available in OCtober.
o Under Guidelines for Writing a Cover Letter, changed the keep to one page
bullet to keep to one or two pages.
o Revised Copyright statement to reflect latest legal requirements.
Mariellen stated that the IPA core team discussed the signoff process and will
be making that process available soon. We plan to informally signoff the
guidelines as a team, then submit the guidelines to IPA for approval.
Bob is collecting input from the team members to determine a better meeting
time.
Action Items:
ACTION: Bob to send out updated guildelines to team for final team approval.
ACTION: Every team member needs to send Bob a list of customers that we plan
to interview. Bob will maintain the list and the team will evaluate it for
diversity.
ACTION: Bob needs get a GM customer contact from Anne Pelagatti (Jill's
supervisor). GM is a UNIX shop.
Next Meeting:
The next meeting will be scheduled soon at a (hopefully) more convienent
time for everyone.
|
| 18.15 | Minutes - Oct. 5, 1993 | TNPUBS::GOVONI | | Wed Oct 06 1993 14:06 | 92 |
| Release Notes Task Force Minutes
Oct. 5, 1993
Attendees: Mariellen Sheridan
Bob Govoni
Marsha Kinnear
Jill Callander
Cover Letter:
There were a few minor editorial corrections to the guidelines.
Bob will make the changes and submit the finished guidelines to
the IPA core team.
As a member of the core team, Mariellen will determine the impact
of T&N Pubs merging with IDC to the IPA signoff process. Bob will also
talk to Mike Quinn, our IPA representative.
We also discussed creating templates. Mariellen will send the team
PostScript files of the existing Interleaf 7x9 and 8.5x11 templates.
Meeting Time:
Tuesday afternoon is not a good time to meet. (Oversight on the part of the
current chairperson.) It appears that Thursday afternoons, 3-4:30, is
best. Bob will reschedule the meetings.
Release Notes:
There was general agreement that we can finish the release note guidelines
by Thanksgiving.
Mariellen noted that the IPA II quality task force performed several
customer interviews and have release note information from these interviews.
Mariellen will gather this information and distribute to the team.
We looked at the Pathworks release notes and determined that most information
belonged in documentation, not in release notes.
We agreed to include the following in the guidelines:
Strongly recommend that the new features of each point release
be documented, but not in the release notes. This is based on recent
customer input. Also, Jill noted that the installer does not always
install the release notes, then the new features that are important
to the user would not be available to the user.
Publications personnel (writer or editor) should either write or,
at least, review release notes before they are allowed to ship.
Release notes are a document and should be subject to the same
quality standards as other Digital documentation.
There should be no TOC for release notes 7 pages or less.
A title page is not necessary.
Action Items:
ACTION: Mariellen to get PostScript files of 7x9 and 8.5x11 Interleaf
cover letter templates.
ACTION: Bob to reschedule meetings.
ACTION: Mariellen to send terminal server release notes to the team.
ACTION: Jill to send Alarm Manager release notes to the team.
ACTION: Bob to write up draft of release note guidelines in same format as
cover letter guidelines.
ACTION: Bob to send out updated guidelines to team for final team approval.
**DONE**
ACTION: Every team member needs to send Bob a list of customers that we plan
to interview. Bob will maintain the list and the team will evaluate it for
diversity. **N/A now that we have abundant customer input via the quality
task force.**
ACTION: Bob needs get a GM customer contact from Anne Pelagatti (Jill's
supervisor). GM is a UNIX shop. **GM customer considered too sensitive.**
Next Meeting:
The next meeting will be Thursday, Oct. 14 at 3:00. Bob will send out
location.
|
| 18.16 | Minutes - Oct. 14, 1993 | TNPUBS::GOVONI | | Fri Oct 15 1993 14:30 | 87 |
| Release Notes Task Force Minutes
Oct. 14, 1993
Attendees: Bob Govoni
Marsha Kinnear
Cover Letter Templates:
We looked over existing Interleaf cover letters: one was 7x9, the other
was 8.5x11. We decided to take out the product-specific information. We
also will add bullet and paragraph tags to these files. This will give
us the two Interleaf templates.
We considered creating only the Interleaf templates, then making PostScript
files of these templates available in a public directory. We would not,
therefore, create templates for authoring tools, such as DOCUMENT and
MicroSoft Word. Anyone using an authoring tool other than Interleaf
could use the PostScript files as a guideline.
Release Notes:
We looked over the rough draft of the release note guidelines and made
a few organizational changes.
We discussed the need to have the installation overview in the release
notes. We need to provide guidelines around when and why this would
be necessary. One thought is to only have the installation overview
if there is a particular technical "gotcha" that would cause installation
or product failure, which must be brought to the installer's attention.
The overview would be used as a guide for the installer to clarify
when the potential gotcha could occur in the installation process.
Joe O'Connor (manager in a quality group with SQM responsibilities) and
Frank Ferreira have agreed to review the release note guidelines.
We looked over the task force's kickoff meeting minutes. Our first meeting
discussed the type of information that belongs in release notes.
All this information was covered in today's draft EXCEPT for the
following:
o Process for creating release notes
This is a project-dependent process. However, the next draft of the
guidelines will recommend planning the release notes when the
other documentation is planned, which is at the beginning of the project.
o Authoring tools
Today's environment allows a variety of authoring tools, such as DOCUMENT,
Interleaf, MicroSoft Word, etc. The authoring tool is usually project
dependent. We only need to be concerned with the output.
o Benefits to various groups when using these guidelines
These should be self-evident.
We also discussed having a draft of these guidelines ready for IPA review
by the end of the month. To do this, everyone needs to read the draft and
send comments to Bob before Oct. 25.
Action Items:
ACTION: Mariellen to get PostScript files of 7x9 and 8.5x11 Interleaf
cover letter templates.
ACTION: Bob to reschedule meetings. **DONE - Meetings are now on Thursdays at
3:00**
ACTION: Mariellen to send terminal server release notes to the team.
ACTION: Jill to send Alarm Manager release notes to the team.
ACTION: Bob to write up draft of release note guidelines in same format as
cover letter guidelines. **DONE**
Next Meeting:
Next week, Mariellen and Bob will be in a course in Boxborough. Therefore,
the next meeting will be in two weeks, on Thursday, Oct. 28, at 3:00 in the
Oliver Wendell Holmes conference room (LKG1-3).
|
| 18.17 | Minutes - Oct. 28, 1993 | TNPUBS::GOVONI | | Mon Nov 01 1993 11:38 | 91 |
| Release Notes Task Force Minutes
Oct. 28, 1993
Attendees: Bob Govoni
Mariellen Sheridan
Larry Holmes
Cover Letter:
Early in the day, Bob, Larry, and Mariellen attended the IPA core
meeting. The purpose was to present the cover letter guidelines and
templates for final approval. The approval was given upon the following
conditions:
o Verify that DEC Standard 073 does not require the Digital logo to be
on the left side of the cover letter. Currently, the template has the
Digital logo on the right side.
o The definition of a cover letter in the guidelines is not complete.
Add one or two sentences for clarity. Also, change the wording of the
example in the definition to not mislead readers to believe that
cover letters are forbidden in V1.0 products.
o Place the date in the title of the guidelines.
o Create a sample cover letter.
o A few minor editorial comments.
ACTION: Bob will check with Alice Phalen on the 073 issue.
ACTION: Mariellen will send the TSM cover letter to the team for possible
use as the cover letter sample.
Overall, the IPA core team was very positive over the cover letter
guidelines.
Release Notes:
At the IPA core meeting, we took the opportunity to pass out the first
draft of the release note guidelines for review. The core team committed
to sending us comments by Wednesday, Nov. 3.
At the team meeting, we reviewed the guidelines and the customer input
gathered by the IPA II Quality Task Force. We proposed the following
changes:
o Add information about disk space requirments under installation overview.
o Add a bullet under installation overview for those products that have
no installation procedure (i.e., Flash ROM).
o Add a recommendations section at the end of the guidelines. This section
will discuss scheduling when to write release notes and how to
handle when engineering writes the release notes. We will suggest
that this type of information is covered in the documentation plan.
o Add some discussion about whether or not to print release notes; however,
we understand that this is mainly a project-dependent decision.
We discussed adding new features to the release notes. After some
discussion, we decided to edit the existing bullet about new features
(under Additional Guidelines) for clarity.
ACTION: Mariellen to send latest terminal server release notes to team for
possible use as the release notes sample.
Action Items:
ACTION: Bob will check with Alice Phalen on the 073 issue.
ACTION: Mariellen will send the TSM cover letter to the team for possible
use as the cover letter sample.
ACTION: Mariellen to get PostScript files of 7x9 and 8.5x11 Interleaf
cover letter templates. **DONE**
ACTION: Mariellen to send terminal server release notes to the team.
ACTION: Jill to send Alarm Manager release notes to the team.
Next Meeting:
The next meeting will be on Thursday, Nov. 3, at 3:00 in the
Oliver Wendell Holmes conference room (LKG1-3).
|
| 18.18 | Minutes - Nov. 11, 1993 | TNPUBS::GOVONI | | Thu Nov 11 1993 21:38 | 87 |
| Release Notes Task Force Minutes
Nov. 11, 1993
Attendees: Bob Govoni
Larry Holmes
Cover Letter:
Sample cover letters are done and in the Interleaf IPA cabinet. The
TSM cover letter was modified and became the 7x9 sample. A DECmcc cover
letter was modified and became the 8.5x11 sample.
Bob checked with Alice Phalen to determine if DEC Standard 073 requires
a specific placement of the Digital logo (left or right side). The
standard had no such requirement. For consistency, the guidelines
suggest placing the logo on the right side.
Bob will send Bruce Gillham a message asking where to place the cover letter
guidelines file.
This concludes our work with cover letters!
Release Notes:
Discussed the latest draft of the release note guidelines. All comments
from the IPA core team have been incorporated. The guidelines are nearly
complete. Need to add the following comments from Jill:
o Add one line near the front as to why the order of the sections in
the release notes should be maintained would be useful. You
say maintain them but not why; my reasoning is for consistency
across products, and because the order moves through the order
in which the product is introduced to the user (install, then use)
o Near the end you tell them to name the files read me or release_notes
this should be clarified, that on vms the file should be name
ProductName_release_notes.txt, and should be placed (optionally)
in the sys$help directory. Because it is a common directory
each release note must be distinguishable by product name.
Also need to add Larry's comments:
o Under Format and Content, emphasis that most sections are optional
before listing the titles.
o Add that the Digital logo is not required on the title page (confirmed
by SQM representative).
o Under Output formats, clarify the term UNIX-based system.
Currently, two SQM representatives are also reviewing these guidelines.
The only comment so far is to add that online release notes are now
legally required to be available in ASCII.
The only question left to answer is: does an SDML release notes template
exist?
We also reviewed the release notes sample. There were no comments.
Unless anyone on the team has comments, this sample is final.
At our next (last) meeting, we will finalize the guidelines and send
both sample and guidelines to the IPA core for review. If no comments,
then we're done.
Action Items:
ACTION: Bob to determine if an SDML release note template exists.
ACTION: Bob will check with Alice Phalen on the 073 issue. **DONE**
ACTION: Mariellen will send the TSM cover letter to the team for possible
use as the cover letter sample. **DONE**
ACTION: Mariellen to send terminal server release notes to the team. **DONE**
ACTION: Jill to send Alarm Manager release notes to the team.
Next Meeting:
The next meeting is our last scheduled meeting. It will be held on
Thursday, Nov. 18, at 3:00 in the Oliver Wendell Holmes conference room
(LKG1-3).
|
| 18.19 | Minutes (Final) - Nov. 18, 1993 | TNPUBS::GOVONI | | Fri Nov 19 1993 09:26 | 39 |
| Release Notes Task Force Minutes
Nov. 18, 1993
Attendees: Bob Govoni
Mariellen Sheridan
Cynthia Day
Jill Callander
Marsha Kinnear
We reviewed the release note guidelines as a team. There were no
content changes; however, there were a number of editorial changes to
improve clarity. We also discovered that the sample release notes
document was missing the copyright statement.
Bob will update the guidelines and sample document, then send them to
Bruce Gillham for IPA review, as well as this team.
The next IPA core team meeting is Dec. 2. At that time, we expect to
have the final comments and IPA signoff.
This was our last official team meeting! But we do plan to go out to
the week of the 6th.
Currently, two SQM representatives are also reviewing these guidelines.
Action Items:
ACTION: Bob to determine if an SDML release note template exists. **DONE -
No template exists**
ACTION: Jill to send Alarm Manager release notes to the team. **N/A now!**
Next Meeting:
Dec. 2 at the IPA core team meeting.
|
| 18.20 | Release Notes Guidelines - SDML | TNPUBS::GILLHAM | | Fri Mar 11 1994 13:15 | 399 |
| From: TNPUBS::GOVONI "DTN 227-3268 _ TTFN (Ta Ta For Now!) 02-Dec-1993 1656" 2-DEC-1993 16:56:45.33
To: GILLHAM
CC: GOVONI
Subj: Release Notes source file (SDML)
<document_attributes>
<set_headings>(unnumbered)
<enddocument_attributes>
<head1>(Release Note Guidelines - Nov. 19, 1993\rl_note)
<p>
These guidelines define the purpose of release notes, provide format and style
rules for creating release notes, describe various output formats, and provide
a list of reference documents.
<note>
These guidelines were written by the IPA III Release Notes Task Force:
Jill Callander,
Cynthia Day,
Bob Govoni,
Larry Holmes,
Marsha Kinnear, and
Mariellen Sheridan
<endnote>
<head2>(Definition\definitions)
<p>
Release notes are a document that conveys to the customer important technical
information not contained in other documentation. The purpose of release
notes is to provide information about last minute changes to the product. The
goal is to keep the release notes as short as possible.
<p>
Release notes are normally required to ship a product. The release notes are
packaged with the product and are available to all customers of that product.
<head2>(Format and Content\format)
<p>
The release notes should be organized into the following sections. Most
sections are optional and should be used only as necessary.
<list>(numbered)
<le>Title page (not optional)
<le>Table of Contents
<le>Installation Overview
<le>Potential Installation Problems
<le>Installation Document Changes
<le>Known Problems and Restrictions
<le>Resolved Problems From the Previous Release
<le>Documentation Changes
<endlist>
<p>
You need to maintain the order of these sections. Customers have indicated
that they expect to see installation information first. In addition,
maintaining the order of the sections
helps with consistency across multiple products.
<p>
You can insert additional sections as necessary. If you have a large amount
of information in one section, you might need to reorganize that information
for readability. For example, a product installed on multiple platforms
might need a Potential Installation Problems section for each platform.
<page>
<p>
The following describes each section in detail:
<list>(unnumbered)
<le>Title Page
<p>
The title page is the first page of the release notes. It consists of the
product name, version number, title, document part number (only necessary
when the release notes are printed and shipped), date (month and year)
short product description, and copyright statement. The following shows the
format:
<code_example>
__________________________________________________________________________
Product Name(tm) Version X.X Release Notes
<emphasis>(Part Number:XX-XXXXX-XX\bold)
November 1993
Short product description.
<endcode_example>
<p>
The date is based on the SSB submit date. If the SSB date is before the
15th of a month (for example, April), the release notes date is that month
(April). If the SSB date is after the 15th of a month (April), the release
notes date is the following month (May).
<note>
The Digital logo is not required in the release notes.
<endnote>
<p>
The product description should be no more than one or two lines. This appears
as a paragraph immediately after the heading. By providing a short description,
the customers know they have the correct release notes and have a general
description of the product.
<p>
Optionally, you can add a second paragraph to specify who should read the
release notes.
<p>
Use the following copyright statement in the footer area of the title page:
<code_example>
(c) Digital Equipment Corporation 1993 o All rights reserved o Printed in U.S.A.
<endcode_example>
<p>
Throughout the release notes, mark all first instances of copyrights and
trademarks appropriately
(for example, LAT<special_char>(trademark_symbol) or
MS-DOS<special_char>(registered_symbol)). A list of trademark owners (such as
in the documentation) is not necessary; therefore, do not create a copyright
page.
<le>Table of Contents
<p>Only include a table of contents when the release notes exceed seven pages.
<p>
The table of contents starts on the page after the title page. If the entire
table of contents can fit on the title page, then place it after the product
description.
<le>Installation Overview (optional)
<p>
For various reasons, it is sometimes appropriate to provide a high-level
overview of the installation process. The overview can either be a numbered
procedure, a diagram, or both. However, the overview should not take
more than one page of the release notes. This overview should reference the
installation document for details.
<p>
The reasons for providing the installation overview include:
<list>(unnumbered\-)
<le>The installation document is online only (especially with CD-ROM releases)
and is not accessible without starting the installation process.
<le>The software installs automatically, such as products with Flash RAMs.
<endlist>
<p>
Within the installation overview, you can either state the preinstallation
requirements, such as disk space, or point to the documentation for this
information.
<le>Potential Installation Problems
<p>
Provide a list of those problems or potential oversights that could cause the
installation process or product to fail. For example:
<list>(unnumbered\-)
<le>The product works with only particular versions of another product.
<le>The installation process does not check for disk space. This must be
done by the installer.
<le>This product cannot coexist with another product on the same processor.
<le>For OpenVMS products, this product cannot run across a cluster but must be
installed on a single cluster member.
<endlist>
<p>
Most, if not all, of these problems should appear in the installation
documentation. List only those problems or oversights that are either not
documented or you feel could be easily overlooked in the documentation.
If the problems do appear in the documentation, refer to the documentation
for details.
<p>
If you also have a high-level overview, you could combine these two sections.
The reason would be to show where these problems could occur in the installation
process.
<le>Installation Document Changes
<p>
Document all changes to the installation process not covered in the manual.
<le>Known Problems and Restrictions
<p>
Describe all known problems and their workarounds, if any. These problems
include incompatibility issues and product restrictions.
<p>
State any incompatibility issues between this release of the product and
the previous releases. Also state any incompatibility issues with other
products as of this release.
<p>If this information is covered in the documentation, mention only those
critical (causes product failure) issues and restrictions, and reference the
document for the detailed information.
<p>
Identifying known problems can reduce the number of Quality Assurance Reports
(QARs) and Software Performance Reports (SPRs) from customers.
<p>
For an Engineering Change Order (ECO) or Mandatory Update (MUP), DEC Standard
204 requires that the release notes describe the MUP or ECO problem and its
solution.
<le>Resolved Problems from the Previous Release
<p>
Describe the problems with the previous release and their solutions.
<le>Documentation Changes
<p>
Describe any corrections or additions to the documentation.
<endlist>
<head2>(Additional Guidelines\guide)
<p>
The following lists general guidelines to follow when writing release notes:
<list>(unnumbered)
<LE>
Schedule the activity of writing the release notes at the beginning of the
project.
<p>
Often, release notes are an unplanned last-minute activity, which is reflected
in its quality.
<p>
Ensure that the scheduling information is captured in the documentation
plan.
<le>At the beginning of the project, determine who will write the release
notes.
<p>
The project team should determine who will write the release notes, namely,
a writer or an engineer. A writer is preferable; however, these guidelines
should be followed by whomever writes the release notes. Ensure that the name
of the designated release notes author is included in the documentation plan.
<le>
According to DEC Standard 204, release notes are mandatory with ECOs
and MUPs. The release notes must describe the MUP or ECO problem
and its solution.
<p>
You must also include the following statement in release notes for ECOs
and MUPs:
<code_example>
The software contained on this media is proprietary to and embodies the
confidential technology of Digital Equipment Corporation. Possession, use,
duplication, or dissemination of the software and media is authorized only
pursuant to a valid written license from Digital Equipment Corporation.
<endcode_example>
<le>Do not provide procedures on how to report problems.
<p>
Software Problem Reports (SPRs) are automatically shipped to software
customers, and hardcopy documentation contains a reader's comments card.
<le>For point releases, do not list the new features unless the new
features are not listed in the other documentation.
<p>
Based on customer input, we find that customers need to see a list of
new features for each point release. Many customers will skip a point release
and they need to see what new features have been provided for each release.
Customers would like to see this in online help or the documentation, not
necessarily the release notes.
<le>Release notes are a document and are subject to the same policies and
quality standards as other documentation. Although the release notes author
could be a technical writer or an engineer, someone from the publications
group needs to have input into the release notes to ensure adherence to
quality standards, such as spelling, grammar, and conciseness.
<le>
The information in field test release notes should either be resolved or
incorporated in the documentation, making it unnecessary to be in the final
release notes.
<endlist>
<head2>(Output Formats\output)
<p>
For release notes that are available online, you need to name the file
appropriately. In the PC world, the file is named README.TXT. For OpenVMS and
UNIX-based (ULTRIX, OSF/1) systems, the file is usually named
PRODUCT_NAME_RELEASE_NOTES.TXT. On OpenVMS systems, product release notes are
normally placed in the SYS$HELP directory. Because it is a common directory,
each release note must be distinguishable by product name.
<p>
Once written, release notes are usually converted to various formats, such as
ASCII, PostScript, and other online formats, to satisfy the needs of various
distribution channels. The distribution channels that you use for your release
notes will depend on your project. The distribution channels include:
<list>(unnumbered)
<le>ConDist
<le>CDROM
<le>SSB
<le>TIMA (maintains a database of ECOs and MUPs for the field)
<p>
TIMA often requires that keywords are included in the ASCII version
of the release notes file. Refer to the DEC Standard 204 or your TIMA
representative for additional information.
<endlist>
<note>(IMPORTANT)
It is a legal requirement that online release notes be available as an ASCII
file.
<endnote>
<head2>(Printed Release Notes\printed)
<p>
For some projects, it is desirable to send printed release notes with the
product. The advantages of printed release notes include:
<list>(unnumbered)
<le>Customer has easy and immediate access to the release notes.
<le>Preinstallation changes can be included in the release notes.
<endlist>
<p>
If your release notes are available in printed and online formats, both versions
must be exactly the same to avoid customer confusion.
<p>
Keep the printed release notes the same size as the documentation (for
example, 8.5x11 or 7x9).
<head2>(References\references)
<p>
The following are standards and other documents that could impact
release notes:
<list>(unnumbered)
<le>DEC Standard 073 (production information only)
<le>DEC Standard 197
<le>DEC Standard 204
<le>Technical Requirement Guides (for the various operating systems)
<endlist>
<p>These documents are available through VTX SMC.
|
| 18.21 | Sample Release Notes | TNPUBS::GILLHAM | | Fri Mar 11 1994 13:17 | 925 |
| From: TNPUBS::GOVONI "DTN 227-3268 _ TTFN (Ta Ta For Now!) 02-Dec-1993 1657" 2-DEC-1993 16:57:53.00
To: GILLHAM
CC: GOVONI
Subj: Sample Release Notes source file (SDML)
<front_matter>(f_matter)
<title_page>
<title>(DECserver<special_char>(trademark_symbol) Network Access Software
Version 1.3 Release Notes)
<abstract>
<p>
<emphasis>(Part Number: AA-PX0QC-TE \bold)
<p>
November 1993
<p>
The DECserver Network Access Software Version 1.3 Release Notes contain
information about potential installation problems, known problems,
and resolved problems from the previous release.
<P>
The Release Notes should be distributed to the network access server
manager(s), load host system manager(s), and any other
individuals responsible for network access server maintenance.
<endabstract>
<line>
<line>
<line>
<line>
<line>
<line>
<line>
<line>
<line>
<line>
<line>
<line>
<line>
<line>
<p>
<mcs>(copyright)
<code_example>(Digital Equipment Corporation 1993 o All rights reserved o Printed in U.S.A.)
<endtitle_page>
<contents_file>
<endfront_matter>
<page>
<head1>(Potential Installation Problems)
<p>
This section provides information to help avoid problems that could occur
during installation.
<head2>(UNIX Host Installation)
<p>
If this kit is being installed on a UNIX host, ensure that you read the README
file provided with the installation kit. It
includes examples and hints relevant to the installation procedure,
specifically, the making of CMU BOOTP sources on different UNIX systems and
platforms. Note that the CMU BOOTP sources are provided only as a convenience to
those users that do not have BOOTP in their systems. Digital Equipment
Corporation does
not offer any support of the BOOTP sources nor does it provide any warranties
on their operation.
<head2>(OpenVMS Installation)
<p>
DSV$CONFIGURE.COM requires the NET$MANAGE rights identifier, when used
on DECnet/OSI (Phase V) systems. Use of the SYSTEM account is not
sufficient.
<head2>(Down Line Image Loading)
<p>
The load image files provided for DECserver Network Access Software V1.3 on the
DECserver 90TL (with 4 MB of RAM) or DECserver 90M platforms is compressed.
The raw image size is larger
than 1 MB. Since the DECserver 90M Flash RAM option is limited to 1 MB in size,
only compressed images will fit into Flash RAM. This applies to the MNENG2
image only, and applies equally to the MNENG2 image loaded via the network
or loaded from Flash
RAM. The MNENG1 DECserver 90TL V1.1 image, the WWENG1 image for
DECserver 700, and the WWENG2 image for DECserver 700 and 900TM remain
uncompressed.
<p>
As a side effect of loading a compressed MNENG2 image, the
DECserver 90TL (with 4 MB of RAM) or the DECserver 90M will take approximately
<emphasis>(four additional minutes\bold) to complete down line loading and
image decompression.
The DECserver may appear non-functional during this time. This is normal.
<head2>(Booting the Access Server with Flash RAM)
<p>
If your access server has Flash RAM, refer to the Network Access
Server Management Manual for more information.
<head2>(Disk Space Requirements)
<p>
The following information refers to the disk space required on the
load host's system disk. The disk space size is approximate.
(Actual sizes may
vary depending on the user's system environment, configuration, and
software options.)
<p>
<emphasis>(For OpenVMS (VAX and Alpha) systems:)
<TABLE>
<TABLE_ATTRIBUTES>(SINGLE_SPACED)
<TABLE_SETUP>(2\25)
<TABLE_ROW>(Disk space required for installation and
<line> permanent storage:\6,500 blocks)
<ENDTABLE>
<p>
<emphasis>(For ULTRIX systems:)
<TABLE>
<TABLE_ATTRIBUTES>(SINGLE_SPACED)
<TABLE_SETUP>(2\25)
<table_row>(Disk space required for installation and
<line> permanent storage:\4,500 KB)
<endtable>
<p>
<emphasis>(For MS-DOS systems:)
<TABLE>
<TABLE_ATTRIBUTES>(SINGLE_SPACED)
<TABLE_SETUP>(2\25)
<table_row>(Disk space required for installation and
<line> permanent storage:\3.4 MB)
<endtable>
<p>
<emphasis>(For UNIX systems:)
<TABLE>
<TABLE_ATTRIBUTES>(SINGLE_SPACED)
<TABLE_SETUP>(2\25)
<table_row>(Disk space required for installation and
<line> permanent storage:\5,000 KB)
<endtable>
<p>
<emphasis>(For AXP OSF/1 systems:)
<TABLE>
<TABLE_ATTRIBUTES>(SINGLE_SPACED)
<TABLE_SETUP>(2\25)
<table_row>(Disk space required for installation and
<line> permanent storage:\4,500 KB)
<endtable>
<head1>(Known Problems)
<p>
The following list includes some of the known problems with this
release of the DECserver Network Access Software. Workarounds are
described where applicable.
<head2>(AppleTalk)
<p>
There are certain situations that may cause an attached AppleTalk host
to have a <quote>(stale) AppleTalk address (an address not contained in the
current network range). This will occur if the the network range
changes during the lifetime of an ATCP connection, such that the
connection's address is not within the new range. Examples of this
might be if the routers on a network were reconfigured with a new
network range or if no routers were active and then one or more
routers began functioning. The user will not be notified of the new
network configuration and will continue to operate with this
<quote>(stale)
address. This situation may not disrupt current network service
connections but may inhibit future service connections.
<p>
Unfortunately, it may be difficult for the user to distinguish this
problem from other unrelated network problems (e.g. routers going
down). In general, if the user sees reduced service access, they
should try disconnecting the ATCP connection (making sure the port
gets logged out, e.g. due to modem control) and then reconnecting. At
this time the connection will be given a valid address within the
current network range.
<head2>(TN3270 Enhancement)
<p>
Abbreviating keymap and/or terminal names is no longer acceptable.
This was allowed in the previous version, when the terminal and keymap
names were known and abbreviations could be assumed to be unambiguous.
Now, however, since the system manager can create new terminal and
keymap names, abbreviations might be ambiguous.
<head2>(Information for TSM Users)
<p>
<emphasis>(For OpenVMS systems only\bold)
<p>
If you have TSM V2.0 installed, you should be able to run with this
new version of DECserver Network Access Software. To utilize the new
terminal server commands available on the terminal server through TSM,
use the SYNTAX CHECK DISABLE command on TSM. This allows TSM to bypass
parsing the command, and pass it directly to the terminal server.
<p>
There are some known problems with this feature, for example, if the
command is DEFINE APPLETALK DISABLED, TSM will crash. The current
work around is to abbreviate the words in the command to either 26 or
28 characters. If you are using TSM V2.0 an update is available which
will correct this problem. Ask your Digital contact to get you a copy
of TSM V2.0-03.
<p>
If you are running TSM version V1.6 managing the DECserver 90M,
platform, you must add the new terminal server type into TSM before
adding the terminal server to TSM. Note that some of the newer
terminal server commands will not be recognized by TSM, and will not
be passed through to the terminal server.
<p>
The work around for TSM Version V1.6 is to use the PASTHRU command to
connect directly to the terminal server, bypassing TSM's syntax
parsing functions.
<p>
TSM V2.0 users who will be using TSM with DECserver 90M terminal
servers may wish to get an updated version of TSM. Ask your Digital
contact to get a copy of TSM version V2.0-03.
<head2>(Telnet Remote Console)
<p>
When memory utilization is at or near 100%, a Telnet remote console
connection request to the access server may be rejected.
<head2>(PING)
<p>
There is a bug in the software which causes the output from a
completed PING to be displayed in local mode instead of in session
mode. This will happen if the user starts a PING session, hits the
break key, and does not resume the PING session before the test
completes. If the user remains in session mode, the PING output will
be displayed properly.
<head2>(Domain Name System (DNS))
<list>(unnumbered)
<le>
Do not use the SET or DEFINE INTERNET HOST command to enter a large
number of LOCAL entries, unless the name resolution mode is LOCAL.
The reason for this restriction is that if the DNS cache is full,
certain commands invoke an automatic purging of LEARNED entries. If
most or all of the entries are LOCAL (SET or DEFINEd entries), then
the automatic purging of LEARNED host information will not free much
memory. One effect of not freeing much memory is that the name
resolution phase of connecting to an internet host (for example, when
you see the "Resolving name..." on the screen), when the RESOLUTION
MODE is REMOTE or ORDERED, can take an extraordinarily long time to
complete. This is because the lack of DNS cache memory is causing the
code to be extremely time inefficient.
<le>
When multiple DNS entries exist for an internet host name
(a multi-homed host), the Telnet code will only use the first
one returned by DNS. There is no load-sharing or failover. It is
not easy for the user to be certain of which internet address was
at the top of the list, so caution should be used with multi-homed
hosts.
<endlist>
<head2>(Telnet Server Session Echo)
<p>
A Telnet server session to a network access server physical port made
through the Telnet listener will respond with WILL-ECHO to a DO-ECHO request
from a Telnet client; however, the access server will not actually perform
echoing. Echoing of incoming network data is the responsibility of the
device attached to the physical port.
<head2>(User Authentication)
<p>
The documentation indicates that User Authentication requests may be
aborted by the user, once all information has been entered and the
actual request has been sent onto the network, by typing a Break or
local-switch character on the terminal. This feature is not
implemented in the current release. Once the request is sent to the
Kerberos KDC, the user must wait for a response from the KDC or a
timeout to occur before additional local mode commands may be entered.
The timeout is controlled by the SET|DEFINE|CHANGE KERBEROS TIMEOUT
command. This limitation applies to both user login authentication
and the KPASSWD command.
<head2>(SNMP)
<p>
The <emphasis>(SNMP Survival Guide) (snmp_survival.txt) included in
the release kit provides the system manager with all the necessary
information to manage the DECserver using SNMP.
<p>
The Survival Guide indicates that the atPortType object reports
other(1) when there are no AppleTalk (ATCP/PPP) sessions. This is
incorrect. atPortType reports serial-ppp(7) at all times for the
asynch ports.
<p>
The Survival Guide also incorrectly indicates that the atPortStatus
object reports off(3) when the port has been configured to run
AppleTalk, but has no AppleTalk session. This object reports
unconfigured(2) in that situation.
<p>
The DECserver Network Access Software, Version 1.3 does not support the
atEcho group of the AppleTalk MIB.
<head2>(Modems)
<p>
Although the DECserver 90TL and DECserver 90M
do not support full modem control, some
Digital Scholar modems have been known to work under certain configurations.
Generally, the modems operate in a rudimentary way using default
characteristics with some modifications. Not all features and modes of the
Scholar work. Features like Multi-speed protocol and Fallback are not
supported. The following Digital Scholar models are known to have operated
with the DECserver 90TL in dial-in or dial-out configurations:
<code_example>
DECmodem V32
DF242
DF224
DF212
<endcode_example>
<p>
Other modems, with similar functions and characteristics, may also work in
a similar configuration. Refer to the System Support Addendum (SSA) of the
DECserver 90TL Software Product Description (SPD) for additional information
on modem usage.
<p>
Use a connection scheme where modem DSR, DTR will be tied directly to
the DECserver 90TL (or DECserver 90M) DSR, DTR respectively.
Recommended cable: Digital
BN24H (or BN25H) 6 conductor cable with MP8 connector on one end and MMP
connector on the other. Recommended adapter: Digital H8571-D MMJ to 25-pin
D-connector, male. Connect MMP end of cable to Adapter. Connect 25-pin
adapter to modem and MP8 end of cable to DECserver 90TL MJ8 port.
Note: MMP means Modified Modular Plug, MMJ means Modified Modular Jack,
MP8 means 8-pin Modular Plug, and MJ8 means 8-pin Modular Jack (sometimes
referred to as RJ45).
<page>
<code_example>
DECserver 90TL/DECserver 90M PORT SETTINGS
------------------------------------------
Port Characteristic DIAL-OUT DIAL-IN
------------------- -------- -------
ACCESS Remote Local
AUTOBAUD Disabled(1) Enabled
AUTOCONNECT Disabled Enabled
AUTOPROMPT Disabled Enabled
BREAK Disabled Disabled(2)
DEDICATED None None
DSRLOGOUT Disabled Disabled
DTRWAIT Enabled Disabled
FLOW CONTROL XON XON
INACTIVITY LOGOUT Disabled Enabled
INTERRUPTS Disabled Disabled
SIGNAL CHECK Disabled Disabled
SIGNAL CONTROL Enabled Enabled
PASSWORD Disabled Enabled
(1) Match port speed with modem speed.
(2) Define a port LOCAL SWITCH character.
MODEM SETTINGS
--------------
Scholar modems have been known to work with the following
configured characteristics:
DECmodem V32, DF242 (Scholar Plus), DF212 :
- Reset to Factory Settings ==> DEF P/ALL
- Adjust Line Speed ==> SET P1/OPE
DF224:
- Reset to Factory Settings
- Adjust Line Speed
Use MODE BELL212=0 or V22bis=2
- Modem Response
Use MODEM RESPONSE ABBREVIATED=0
(recommended on dial-in lines)
<endcode_example>
<head2>(Other)
<p>
Other known problems with this software release are listed below.
<list>(unnumbered)
<le>
The INITIALIZE command does not properly measure the amount of delay time
until the command is invoked. Add 1 minute to the time you specify to make
sure an adequate delay takes place before the access server is initialized.
<le>
When setting up internet gateways, the following considerations
must be kept in mind:
<list>(unnumbered\-)
<le>The subnet mask must be at least as long as the network class portion.
The network class portion will be one, two, or three bytes based on the
IP address.
<le>Network 17.1.1.1 mask 255.0.0.0 is illegal, since its network portion
has extra bits not included in the subnet mask.
<le>All subnet masks must have contiguous ones, starting from the left.
<le>Network xxxx mask 255.255.255.255 is illegal. Use HOST xxxx instead.
<endlist>
<le>On OpenVMS systems, limitations apply to the TSM GET CHARACTERISTIC command
procedure which
causes it to truncate a port Username if the Username has embedded spaces.
When using TSM$NA_V13_GET_CHAR.COM, the following guidelines apply:
<list>(unnumbered\-)
<le>The port Username can be an ASCII character string of up to 16
characters, optionally containing up to 4 embedded spaces. A port
Username containing 4 embedded spaces would therefore contain 5
ASCII substrings which collectively form the port Username.
For example: define port [n] username "Port 1 A B C"
<le>A port Username, whose substring components are separated by multiple
spaces, will be compressed thus reducing multiple spaces to single
space between the ASCII substrings. For example, a port Username defined with:
define port [n] username "A B C D" will result in the command:
"define port [n] username "A B C D"" being generated and placed in the
<emphasis>(server)_SETUP.COM file.
<le>A port Username consisting of more than 5 ASCII substrings will be
truncated thus leaving the first 5 ASCII substrings to form the
port Username. Single characters or substrings beyond the 5th substring
in the Username will be discarded.
<endlist>
<endlist>
<head1>(Known Problems with Other Telnet Implementations)
<p>
The following list includes some of the known Telenet problems with this
release of the DECserver Network Access Software. Workarounds are
described where applicable.
<head2>(Aborting Output - Forever!)
<p>
Symptoms:
<p>
After invoking the Abort Output (AO) function, the
session appears to be hung - output is never resumed.
The Abort Output function could have been invoked by:
<list>(unnumbered)
<le>entering the AO character (default: ^O) in
session mode.
<le>entering another special character which has an
automatic AO (default: ^Y) in session mode.
<le>entering "SEND TELNET AO" in local mode.
<endlist>
<p>
Problem:
<p>
Some foreign vendor Telnet Server implementations do
not reliably respond to the DO Timing Mark request.
This request is used to abort output effectively on
a Telnet session.
<p>
Solutions:
<list>(numbered)
<le>Once "hung", you can recover by entering local
mode and typing "SEND TELNET RESUME OUTPUT".
<le>You can avoid the "hang" for functions which have
automatic AO (IP) by disabling the autoflush
feature with respect to that function. For example:
<endlist>
<code_example>
"SET PORT/SESSION TELNET AUTOFLUSH IP DISABLE"
<endcode_example>
<p>
disables it for the IP function.
Subsequent invokations of the IP function will not
include an AO, therefore will not experience the
"hang".
<head2>(AYT Requires an Extra Character)
<p>
Symptoms:
<p>
After invoking the Are You There (AYT) function, one
character (any character) must be entered before the
AYT response can be seen.
<p>
The AYT function could have been invoked by:
<list>(unnumbered)
<le>entering the AYT character (default: ^T) in session
mode.
<le>entering "SEND TELNET AYT" in local mode.
<endlist>
<p>
Problem:
<p>
Some foreign vendor Telnet Server implementations do
not respond to the AYT request until a subsequent data
character is entered.
<p>
Solution:
<p>
Enter any character.
<head2>(Double Login Prompt from ULTRIX)
<p>Symptoms:
<p>
When telnetting to an ULTRIX V4.0 (Rev. 179) system,
the "login:" prompt is entered twice. It does not appear
to matter what you enter in response to the first login:
prompt, you will always get a second prompt.
<p>
Problem:
<p>
A bug in ULTRIX V4.0 (Rev. 179).
<p>
Solution:
<p>
Answer the first login prompt (type anything). Then answer
the second (with a valid login id). Then you will be
prompted for your password. Proceed normally.
<head2>(Going from Binary to Character Profile)
<p>
A Telnet Client session to a VMS/UCX 5.3 host may not always successfully
negotiate a transition from Telnet Profile Binary to Telnet Profile Character.
Although Telnet Port Session Status for Will-Binary and Do-Binary
indicates <quote>(Disabled), the VMS terminal is left with the PASSALL characteristic,
causing unexpected response to certain input characters.
<p>
This situation can occur when the initial connection establishment to
VMS with Telnet Profile Binary is interrupted by doing a
BREAK to
Local during the VMS login, specifically while the account login is
performing a <line>SET TERMINAL/INQUIRE. If the Telnet session is changed to
Telnet Profile Character, and then resumed, Telnet negotiations to
disable Binary will complete but the VMS terminal characteristic PASSALL will
remain.
<p>
To rectify this condition, change the VMS terminal to Interactive by
performing a SET TERMINAL/INTERACTIVE command at the VMS prompt once the login
is complete.
<head2>(Newline Problem)
<p>
A Telnet connection from the terminal server to an ULTRIX-32 V3.0 (Rev 64)
host or
V4.1 (Rev 50) host with LOCAL ECHO enabled may not interpret newline
correctly. This is due to the
fact that ULTRIX modifies the host stty newline characteristic from
<quote>(-nl) to
<quote>(nl) when the Telnet
Echo option is negotiated between server and ULTRIX. This results in the
recognition of only LF to end lines, rather than CRLF. The following is
a workaround after
a Telnet ULTRIX connection is established: go to server Local mode and
change the Telnet session's newline-to-host and newline-from-host
characteristic to <LF> (for example, SET
SESSION TELNET NEWLINE TO HOST <LF> and SET SESSION TELNET NEWLINE
FROM HOST <LF>)
and then resume the session.
<head2>(Double Echo)
<p>
A Telnet session connection from the server to an ULTRIX-32 V4.1 (Rev 50)
host with LOCAL ECHO enabled results in both the server and ULTRIX echoing
input characters. The server negotiates with ULTRIX to disable echo and
ULTRIX complies.
This can be verified by performing a SHOW PORT SESSION STATUS command
and noting that
Do-Echo status transitions from Enabled to Disabled. The server correctly
starts to locally echo input characters; however, ULTRIX incorrectly continues
to echo producing double echoes. If this condition exists, go to server
Local mode and set the Telnet Session to ECHO REMOTE by performing a
SET SESSION TELNET ECHO REMOTE command.
<head2>(Extra Carriage Return At Login)
<p>
When connecting from the access server using Telnet to a VMS
system (running UCX Telnet Server), you may need to enter a
carriage return in order to get the login prompt. This will be corrected in a
future release of UCX.
<head1>(Resolved Problems From the Previous Release)
<p>
The following section describes fixes and enhancements incorporated
in this version of the DECserver Network Access Software.
<head2>(Refusing a Telnet Listener Connection Request)
<p>
A change has been made in the way the Telnet Listener refuses a
connection request when the Telnet Listener port is busy. Previously
if the port was busy, a connection would be established and then a TCP
RST was sent disconnecting the connection. Now, a TCP RST is
immediately sent without establishing the connection.
<p>
This change prevents print spooler jobs with products like
TGV/Multinet from being lost. With the previous method, TGV would not
resubmit the print job if the connection was established before the
TCP RST.
<head2>(Telnet Send Location Option - RFC779)
<p>
The Telnet Send Location Option is now supported. This Telnet option
sends the user's location in a Telnet negotiation to the Telnet server
where it can be used as desired.
<p>
When a user at a network access server creates a Telnet client
connection, a telnet negotiation is sent to the peer as follows:
<line_art>
IAC WILL SEND-LOCATION
<endline_art>
<p>
When the peer responds with a Telnet IAC DO SEND-LOCATION, the Telnet
client session will send a Telnet send-location subnegotiation as
follows If the peer does not respond with the DO response, the client
session will not send the response, but the session will proceed as
normal. Each time the peer sends IAC DO SEND-LOCATION the Telnet
client session will respond with the Telnet send-location
subnegotiation. In this way the peer can <quote>(poll) anytime for the
user's location.
<line_art>
IAC SB SEND-LOCATION <ascii-location> IAC SE
where <ascii-location> is an ascii string formatted as follows:
PNUM=<port-number>:PNAM=<port-name>:
PNUM= port number field identifier
<port-number> ASCII printable characters except ':'
representing the user's port number stored in
the NVRAM of the Network Access Server.
10 characters max.
: field delimeter.
PNAM= port name field identifier
<port-name> ASCII printable characters except ':'
representing the user's port name stored in the
NVRAM of the Network Access Server.
16 characters max.
The string for the factory init name
is 16 spaces. Defining a name in NVRAM
requires privilege. The <port-name> string
can be set by the administrator using
DEFINE/CHANGE PORT NAME commands or viewed
by using the LIST PORT command.
<endline_art>
<head2>(SLIP)
<list>(unnumbered)
<le>If a port has a configured SLIP host address, proper network
operation requires that any host attached to that port have
that SLIP host address. In order to avoid configuration errors, we
recommend configuring the SLIP ports so that they learn the
address of the attached host when that host starts transmitting.
<le>On ports which are performing address learning, the SLIP host
will not be able to receive any IP traffic until the SLIP
host has sent an IP packet and the access server has successfully
learned the host's address.
<le>
If SIGNAL CONTROL is disabled on a dedicated port, the first packet on
the port is used by the DECserver 90TL or DECserver 90M to establish
the SLIP connection, and the packet may be lost during session startup
processing.
<le>
Each port can have only one Internet address at a time.
Multi-homed SLIP hosts are not supported on SLIP lines.
<endlist>
<head2>(LAT Host Initiated Connects)
<p>
With this release of the LAT software, we provide the capability to
disallow host initiated
connects (SET HOST/DTE, print queues) to password protected services (or
to ports that have password protected services associated with them) unless
the correct password has been defined with the LTA device on the OpenVMS host.
<head2>(Remote Console)
<p>
When connected to Remote Console at the login password prompt # using
either MOP or TELNET, a two minute timeout will cause a disconnect of the
console connection if the user does not enter a password.
<p>
When connected to Remote Console using either MOP or TELNET, typing
<quote>(LOGOUT) command at the <quote>(Local) prompt will cause a disconnect of the
console connection. For MOP there may be a small delay before disconnect
is complete.
<head2>(Telnet Remote Console)
<p>When the access server is booted, the console port may receive the message
"Local - Telnet Listener Failed to Bind Socket". This can occur when
one or more Telnet listeners are enabled in the permanent database and
no internet address is defined.
<head2>(Log out of Sessions on Remote or Dynamic Access Ports)
<p>
A connected session to a Remote or Dynamic access port
with Output XOFF'd may not completely logout. The session remains in a
<quote>(disconnecting) state. The port delays complete logout until the port
XOFF condition is cleared, presumably by the attached device. This is
expected behavior so the DECserver can preserve pending output data. This
condition can occur when the user disconnects the session
when the port is XOFF'd.
<p>
If the XOFF condition on the remote port is not expected to be cleared
by the attached device, then the following methods will log out the port:
<list>(unnumbered\-)
<le>
Manually log out the port from a privileged port on the remote
port DECserver. Two logouts may be required.
<le>
If the remote port and attached device use DTR/DSR signals
and with DSRlogout enabled, the port will be logged out
if DSR is toggled by the device.
<le>
Port Inactivity Logout timer expires on the remote port.
<endlist>
<head2>(Multiple Characteristics)
<p>
The feature by which it is possible to specify multiple characteristics on
one command line on a SET PORT or SET SERVER command does not apply to all
commands. (Example: SET INTERNET and SET PORT TELNET commands)
These commands only accept one characteristic per command line.
<head2>(Domain Name System)
<list>(unnumbered)
<le>
If the DNS cache (what you see when you SHOW INTERNET HOST)
is full, certain operations will automatically cause the LEARNED information
in the cache to be deleted: (a) a CONNECT, OPEN or TELNET command that needs
to resolve a DNS name (a connect to an internet host by name rather
than by address), and (b) a SET INTERNET HOST command.
<le>
The CLEAR INTERNET HOST {ALL|LEARNED} command has a side effect that
other forms of the CLEAR INT HOST command do not have.
All memory allocated for the learned cache entries is
freed. Other versions of the command free only part of the
total memory allocated for each such entry.
<le>
When you enter the SET INT NAMESERVER command, the name
server you used is associated with the default domain.
That means the name server will be queried when the
name being resolved "matches" the default domain. If
the name server is not authoritative for the default domain,
it may delegate to another name server, or it may fail to
provide an answer. If it fails, the name resolver in the
DECserver will attempt to find another name server
(go "up the chain of command"). Results may be unexpected.
Keep this in mind when SET/DEF'ing name servers. The best
thing is that the current value of the DECserver's default
domain is the same as the domain for which the name server
you are adding is authoritative.
<endlist>
<head2>(Data Link Layer)
<p>
The data link layer (DLL) counter for User Buffer Unavailable
(SHOW COUNTERS) is expected to be high in large network configurations.
Normally, this would indicate a performance bottleneck in the
receiving node, but this may not be the case.
This counter includes
LAT Multicast Service Announcements that are thrown away by the
DLL-to-LAT interface. There is a specific "throttle" on this
interface to limit the Multicast packets in favor of "real" LAT
traffic (user data).
<head2>(Server Status)
<p>
The CPU utilization indication in the Show Server Status screen will reach
100% long before the server has reached its actual limit in terms of load.
<p>
The CPU memory usage will be higher on an idle box than it was in previous
versions due to the reservation of some guaranteed pool space.
<head2>(Autobaud)
<p>
If Autobaud is defined as enabled in the permanent characteristics, the
SHOW PORT CHARACTERISTICS display for a logged off port
will show the input speed as 4800, but the
output speed will be that contained in the permanent characteristics.
The autobaud speed is 4800 and is only needed to receive.
The transmit speed takes the value defined in the permanent characteristics.
<head2>(Duplicate IP Address)
<p>
The message "Duplicate IP address received from ARP" may appear at the
console port after reboot. This is a result of the access
server ARPing for its own internet address and hearing a response from
another host. This can also occur when connecting to a host using Telnet
Remote Console or when PING is used to a remote host. The implication is
that another host is using the same internet address as that of the
access server. Host internet addresses must be unique, so this condition
should be remedied.
<head2>(Disabled SLIP or PPP Interfaces)
<p>
SNMP has the capability of disabling an asynchronous interface which
prevents datalink protocol connections (PPP, SLIP). It only affects
datalink protocols, so character-stream sessions (using Telnet and LAT
protocols) would not be prevented. The SNMP object which can be used
to enable or disable an interface is the ifAdminStatus object in the
MIB-2 Interfaces Table. For a full description of this variable, refer
to MIB-2 or to the <emphasis>(SNMP Survival Guide) (snmp_survival.txt)
included in the distribution kit.
<p>
The user interface currently does not provide access to the
ifAdminStatus variable, so it may be difficult to troubleshoot a
disabled interface without SNMP. If an asynchronous interface gets
disabled with SNMP, the interface can be reset to <quote>(enabled)
with the UI command SET PORT [SLIP | PPP] ENABLE. This holds true even
if SLIP or PPP is already enabled on the port.
<head2>(Other)
<p>
If there is pending output on a port that is being logged out, then
the port will not be completely logged out until the output is
completely transmitted. Two logouts will log out the port
immediately.
|