[16] in Open-Software-Foundation-News
DCE Documentation Subgroup Meeting Minutes
daemon@ATHENA.MIT.EDU (Mike Leandertz)
Mon Apr 18 17:24:34 1994
Resent-From: Bill Cattey <wdc@MIT.EDU>
Resent-To: osf-news-mtg@menelaus.LOCAL
Date: Mon, 18 Apr 94 13:27:04 EDT
From: "Mike Leandertz" <leandertz@VNET.IBM.COM>
To: sig-doc@osf.org, sig-dce@osf.org
=======================================================================
MINUTES OF 3/22/94 DCE DOC SUBGROUP MEETING
=======================================================================
The DCE DOC Subgroup met in Santa Cruz, CA on 03/22/94. The following
notes highlight contents of the presentations and discussions. For
more detailed information, refer to the presentation packets that were
made available to each attendee or contact the subgroup Chair.
__________
ATTENDEES:
Name Title Company E-mail
###############################################################################
Kathy Digan Pubs Mgr Tandem Digan_Kathleen@Tandem.com
Greg Doench Executive Editor Prentice Hall ggd@prenhall.com
Carol Henderson Tech Writer Unisys carolh@sj.unisys.com
Jeff Kaminski DFS Lead Writer Transarc jeff@transarc.com
Jody Kelly DCE Doc TeamLead IBM Austin jody@ausvm1.vnet.ibm.com
Mike Leandertz DCE Doc Mgr IBM Toronto leandertz@vnet.ibm.com
Michael Lewis Info Prod Mgr AT&T GIS Michael_Lewis@sandiegoCA.NCC.com
Hal Lichtin DCE Doc Mgr OSF hal@osf.org
Haig McNamee Contract Adm. IBM haig@ausvm1.vnet.ibm.com
D.Pfennighaus Project Mgr HP dp@apollo.hp.com
Steve Randall Tech Writer Tandem Randall_Steve@Tandem.com
R.Shiriwastaw Tech Writer Tandem Shiriwastaw_Rosanne@Tandem.com
Ezra Steinberg DCE Tech Writer SCO ezras@sco.com
Jane Wyman DCE Doc TeamLead Tandem Wyman_Jane@Tandem.com
_______
AGENDA:
1. Welcome & Introductions - Leandertz/all
2. DCE 1.1 Documentation Plans (including Beta) - Lichtin
3. DCE DFS Documentation Plans - Lichtin
4. DCE Problem Determination Guide Update - Digan
5. Prentice Hall Update - Doench
6. Documentation "Version Skew" Discussion - all
7. SGML Conversion Update - Lichtin
8. "What's Happening with OSF?" Discussion - Lichtin/all
9. Wrap Up - Leandertz
______________________________
2. DCE 1.1 DOCUMENTATION PLANS
Hal Lichtin presented the highlights of DCE 1.1 in terms of (i) cross
technology improvements, (ii) component-related enhancements: Naming,
Security, IDL compiler, GDS improvements, Audit, administration
(addition of DCECP and DCED), and (iii) major changes to DCE 1.1 doc set.
(i) Cross Technology Improvements include:
- performance improvements
- code cleanup
- internationalization
- serviceability
Some of these have significant impact on the administration
documentation.
(ii) Component-related Enhancements:
Many of these enhancements actually simplify documentation; for example,
don't have to explain how to write an acl_manager in such gruelling
detail.
______
Naming - Hierarchical Cells: a cell root can be cataloged in other
cells' servers
- Subtree Operations: allows bulk operations on naming subtrees
- Multiple Cell Names: cells can have multiple names in a namespace
or have names in different namespaces
________
Security - Delegation: enables intermediary servers to act on initiator's
behalf and with initiator's identity
- Extended Registry Attributes: allows storage of arbitrary
attributes in security service
- GSSAPPI: provides interface to DCE security for non-RPC clients
____________
IDL Compiler - Stub size improvements, Pointers, Arrays, I18N
- Code changes were actually made in 1.0.3; docs will be
updated for 1.1
___
GDS - New gdscp control program, consistent with dcecp
- Additional administrative improvements
- XOM convenience functions
- Strong Authentication Package
- RTROS
- Abandon operation
_____
Audit - Enables auditing of security-related activities
- DTS and Security subcomponents are instrumented
- APIs and commands for accessing and managing auditing
______________
Administration - DCE command interface (dcecp) "replaces" cdscp, rpccp,
sec_admin, acl_edit, rgy_edit, dtscp
- DCE daemon (dced) runs of every DCE host, and replaces
rpcd, sec_clientd
The role and functions of dcecp and dced were presented and discussed
in more detail.
(iii) DCE 1.1 Documentation Set:
It will consist of the following deliverables. Page count will definitely
increase, but readers should benefit from new books to the library and
changes in library structure.
Introduction to OSF DCE
OSF DCE Command Reference
OSF DCE Administration Guide
Vol I: Introduction
Vol II: Core Components
Vol III: GDS
OSF DCE DFS Administration Guide and Reference **TO BE CONFIRMED**
OSF DCE Application Development Reference
OSF DCE Application Development Guide
Vol I: Introduction and Style Guide **NEW**
Vol II: Core Components
Vol III: Directory Services
OSF DCE Problem Determination Guide **NEW**
Porting and Testing Guide*
Release Notes*
Technical Supplement* (will be treated as a directory tree of
specifications and other info, not as a
formal document)
*not published by Prentice Hall
_________________
AES Documentation
Available now: RPC Volume
Still to come: Time Services and Directory Services Volume
-- both accepted by X/Open
-- expect to be published in 3Q94
Threads Services
-- will not go to X/Open
-- will be included in either Time/Directory or Security
Volume
Security Services Volume
-- about to be sent to X/Open for review
-- publication date depends upon review results
_____________
Major Changes
o Significant impacts on the Core Volume of the Administration Guide
because replacing 'old' control program documentation with the
equivalent dcecp functionality.
o Eliminating User's Guide and Reference.
o Changing Administration Reference to a Commands Reference.
o Breaking the Application Development Guide into three volumes
o Adding "Style Guide" as part of Application Development Guide
to describe DCE programming considerations/practices; a programming
example will be included in the doc tree.
o Adding a Problem Determination Guide.
o Removing Diskless documentation from the set.
o Creating a new documentation tree structure.
o Moving the DFS Programming documentation to an "unpublished" directory.
o Deleting NCS documentation from the set.
o A Release Note section will have a "Here's What's New" section to
compare 1.1 with 1.0.3 in an effort to improve the record of DCE
changes.
__________________________
1.1 Documentation Schedule
o 1.1 Beta in 05/94 - Hal emphasized that it will really contain "Alpha+"
quality, and could be compared to a 1.1 snapshot. It is not fully
functional, and the documentation is not a reliable source for
producing 1.1 books:
- some Reference documentation will be "spec" quality
- Problem Determination Guide will be incomplete
- Introduction to DCE will be unchanged
- some dcecp procedures will not be in the Administration Guide
Documentation will be provided in troff/SML, PostScript, ASCII and
machine-converted (filter) SGML formats.
One purpose behind the 1.1 Beta is to solicit FEEDBACK on the doc
set for continuous improvement. Comments/suggestions/corrections
received before the end of July 1994 can be considered and
incorporated into the 1.1 doc set. There are two ways to get your
feedback to the OSF:
1. (preferred) Send your filled-in 'bug report' to dce-defect@osf.org.
The template for this report is found in
<dce-root-dir>/doc/BUGREPORT
As a submitter, you'll receive notification and progress reports
as your feedback gets 'processed'.
2. Send e-mail to Hal Lichtin (hal@osf.org) with your documentation
feedback (negative AND positive).
o General Availability in 11/94
- All documentation complete
- All documentation available in SML source and PostScript output
- All documentation machine converted to SGML source
- Some documentation may be fully converted to SGML
- Prentice Hall documentation preparation begins
____________________________
Related Points of Discussion
o The group debated the best organization of man pages: should they
be grouped alphabetically or broken up into subsections? Hal asked
members to get back to him with their preferences. Hal will make
OSF's decision known once it is made.
ACTION ITEM: Hal Lichtin will solicit input from sig-doc and sig-dce
groups by 4/15/94.
STATUS: E-mail sent by hal@osf.org to sig-doc@osf.org and
sig-dce.osf.org, "Subject: More Documentation Questions", requesting
a response by 4/29/94.
o In light of the elimination of the DFS administrative documentation
from volume 3 of the Administrator's Guide, this book deals exclusively
with GDS. OSF would like to know if you want to see the GDS
Administration book include both the Guide documentation and the
administrative reference pages. This rearrangement is proposed because
some vendors package and license GDS separately from the "core" DCE
functionality.
ACTION ITEM: Hal Lichtin will solicit input from sig-doc and sig-dce
groups by 4/15/94.
STATUS: E-mail sent by hal@osf.org to sig-doc@osf.org and
sig-dce.osf.org, "Subject: More Documentation Questions", requesting
a response by 4/29/94.
o There will be a few instances where the new dcecp will not do what
the old CPs would; these will have to be covered at least in the
reference material.
o dcecp is really an object-oriented program. There will be on manpage
for dcecp, plus 30 object manpages (some long).
______________________________
3. DCE DFS DOCUMENTATION PLANS
The following question was discussed: "Should OSF include DFS
administration documentation as part of the standard docs, or in its
own, independent volume?" Preferences were stated by the companies
represented.
Currently ... Guide information is in Administration Guide, Extended
Services Volume; Reference information is in the
Administration Ref.
Proposal ... Put both DFS in a "DFS Administration Guide and Reference"
It was noted that the majority of companies ship DFS separately and hence
favor the proposal. One concern was raised regarding the size (700+ pp)
of the new publication and its level of usability.
(** Since our discussion, OSF has confirmed that they will proceed **)
(** with a single DFS publication as was proposed. **)
_________________________________________
4. DCE PROBLEM DETERMINATION GUIDE UPDATE
Kathy Digan discussed her work on the Problem Determination Guide.
This book is being created in response to a requirement placed on OSF
by the doc sig about a year ago. Work began with the development of the
SAMS (Symbols and Messages System) tool and the Guidelines for Writing
Messages that were distributed to contributing companies.
The Guide will document approximately 3,000 messages. For currently
documented messages, Kathy has removed detailed information from reference
documentation but retained per-call values for errors.
The Guide organizes messages alphabetically by symbolic code and also
indexes them by numeric code. The book is divided into two parts: Error
Messages (including Status Codes) and Troubleshooting Information.
For each message the following information is provided: code, text,
explanation, action, severity, component, and subcomponent.
Kathy desperately needs material for the troubleshooting sections. She
asks that anyone who has ideas for solving specific problems send them to
digan@osf.org or hal@osf.org.
_______________________
5. PRENTICE HALL UPDATE
The following are available through book stores (quantity discounts
available through Prentice Hall).
AES RPC Volume 0-13-043688-7
Introduction to OSF DCE 0-13-490624-1
OSF DCE User's Guide & Reference 0-13-643842-3
OSF DCE Administration Reference 0-13-643818-0
OSF DCE Administration Guide
Vol I: Introduction 0-13-176546-9
Vol II: Core Components 0-13-176553-1
Vol III: Extended Services 0-13-176561-2
OSF DCE Application Development Reference 0-13-643834-2
OSF DCE Application Development Guide 0-13-643826-1
The majority of these is 1.0.1-based; Administration Ref is 1.0.2.
The covers do not indicate the release level of the documentation. This
was expressed as a concern (and suggestion) during the meeting.
The 1994 OSF Catalogue of Prentice Hall publications is available upon
request from Greg Doench.
__________________________________________
6. DOCUMENTATION "VERSION SKEW" DISCUSSION
The previous agenda item quickly evolved into the subject of version
skew - the published OSF DCE books are back-level to the latest code
available.
Greg Doench updated Prentice Hall publication plans and addressed concerns
about version skews (for instance, the introductory section of the Admin
Guide has changed by one-third for 1.0.3, but none of those changes is
reflected in the Prentice Hall manual). Members voiced their concerns
about the delay between the release of code and the publication of
Prentice Hall books documenting that code. Greg said that Prentice Hall
can arrange for individual transactions with customers, giving them
rougher books, not generally available in bookstores, in less time.
ACTION ITEM: Greg Doench will send out a questionnaire to the sig-doc
to better understand documentation needs for 1.0.3 and 1.1.
Companies interested in making arrangements directly with PH for 1.0.3
books should contact Greg. Turnaround time (prep/print/available) is
8-10 weeks.
OSF has no resource to support 1.0.3 books. OSF also strongly
discourages vendors to ship tape images of 1.0.3 publications because
there were build glitches - information is technically complete but
'visually inappropriate' in spots.
There is a 1.1 publishing plan. Historically it has taken 12-16 weeks
between OSF delivery (to PH) and general availability.
Vendors' plans for 1.1 availability and dependency on 1.1 PH books
was discussed. Continued input to Greg and Hal from vendors was
encouraged.
(** Since our discussion, OSF has begun considering enhancing the **)
(** 'What's Changed' info on the release tape by including the closed **)
(** OT defects as separate files in doc tree. **)
_________________________
7. SGML CONVERSION UPDATE
The 1.1 Beta release will include machine-converted SGML and SML source.
The 1.1 General Availability release will include at a minimum
machine-converted SGML and SML source. Depending upon resources and
schedules, it may also include fully converted SGML.
Future documentation development and delivery is planned to be in SGML.
_____________________________
Technical Publication Toolkit
o Provides the same functionality as the DTE
o Docs will be built using Makefiles (instead of Description files)
o Relies on SGMLS for parsing (public domain)
o Uses LaTeX for formatting to PostScript
o Provides and SGML-to-man converter for reference pages
o Under special agreement, OSF may provide a licensee with tools
to convert OSF DTD documents to SML, HTML (Mosaic), or SDL (COSE).
OSF contact for technical details or questions is Fred Dalrymple
(fred@osf.org).
__________________________________________
8. "WHAT'S HAPPENING WITH OSF?" DISCUSSION
Hal reviewed the planned changes in the OSF organization, emphasizing
that the changes are in the structure and the process, not the goals.
He explained the changes in the funding and develop models that were
announced to the world on the following day.
Some of the relevant points ...
o OSF will retain a two-person documentation team, but primary
contractors will be solely responsible for documenting their work in
the future, as well as integrating material into existing OSF books.
o Each project will have a steering committee consisting of all
project sponsors, end-user representation, OSF. The concern
was raised to OSF that no documentation-specific person was
represented on the steering committee.
o There will be no project development activity at the OSF.
o A DCE 1.2 plan exists and interested primary contractors are being
considered.
o SIGs will continue to exist with OSF representation.
The following questions were submitted to Hal Lichtin ...
o With the new organization, will there be new licensing agreements
written to cover the documentation?
o If a new agreement is written, will the fee structure take into
consideration softcopy distribution (eg. CD-ROM) of documentation?
o If a new agreement is written, will it cover the distribution for
training classes and promotional needs?
o How will documentation be handled with the new model?
o When there is a primary contractor whose commitment is code, there
is always a concern about the quality of the documentation. What
steps are being taken to ensure a contractual obligation on the part
of the primary provider to produce quality documentation?
o Is a documentation person actively participating in the negotiations
with, or planning for, the primary contractor?
Hal agreed to reply to all of these as answers became available (some
require input from Senior Mgmt at the OSF).
__________
9. WRAP UP
It was a long meeting, but proved to be very informative for
all of the attendees. Action items were assigned and should be
completed by the end of April.
The next DCE/MAN SIG was proposed for July 14, 15 in Cambridge.
Super*SIG*Week is scheduled for October 31 - November 4 in Boston.
We did not decide when we should meet again. The above two dates
would be our windows to meet. Please communicate your thoughts
about the next DCE doc Subgroup meeting ... when, agenda items.
Thanks for making our meeting a success. Let's keep in touch.
... Mike
==================================================================
Regards,
M.E. Leandertz
DCE Documentation Working Group Chair
Manager, Information Development
IBM Software Solutions Toronto Laboratory
leandertz@vnet.ibm.com (416) 448-3501
==================================================================
