[93] in Open-Software-Foundation-News
DCE Documentation Working Group Meeting Minutes
daemon@ATHENA.MIT.EDU (Mike Leandertz)
Tue Nov 22 00:03:57 1994
Resent-From: Bill Cattey <wdc@MIT.EDU>
Resent-To: osf-news-mtg@menelaus.LOCAL
Date: Mon, 21 Nov 94 16:24:24 EST
From: "Mike Leandertz" <leandertz@VNET.IBM.COM>
To: sig-doc@osf.org, sig-dce@osf.org
Reply-To: leandertz@VNET.IBM.COM
========================================================================
MINUTES OF 11/02/94 DCE DOCUMENTATION WORKING GROUP MEETING
========================================================================
The DCE Documentation Working Group met in Newton, MA on 11/02/94. The
following notes highlight contents of the presentations and discussions.
For more detailed information, contact the presenter or working group
Chair.
__________
ATTENDEES:
Name Title Company E-mail
########################################################################
Norb Albertson Writer HP norb@apollo.hp.com
Kathy Digan Manager,S/W Pubs Tandem Digan_Kathleen@Tandem.com
Greg Doench Executive Editor Prentice Hall ggd@prenhall.com
Ken Flowers Manager, EngServ OSF flowers@osf.org
Lee Fogal Doc SIG Chair Digital fogal@zk3.dec.com
Marijane Grinham Project Mgr Digital grinham@enet.dec.com
Ray Jones DCE Lead Writer IBM Endicott jonesrt@vnet.ibm.com
Mike Leandertz DCE Doc Mgr IBM Toronto leandertz@vnet.ibm.com
Hal Lichtin DCE Doc Mgr OSF hal@osf.org
Mickey Mann 1.2 Doc Proj Mgr IBM Austin mickmann@vnet.ibm.com
D.Pfennighaus Project Mgr HP dp@apollo.hp.com
Willie Williams New Projects/Doc OSF willie@osf.org
_______
AGENDA:
1. Welcome & Introductions - Fogal/all
2. DCE 1.1 Documentation Status - Lichtin
3. Prentice-Hall Update - Doench
4. DCE 1.2 Documentation discussion - Mann/all
5. PST Process - Flowers
6. Election of new Chair for DCE Doc Working Group
_______________________________
2. DCE 1.1 DOCUMENTATION STATUS
Hal Lichtin gave a presentation on the state of the completed DCE 1.1
documentation set: "At Least as Good as the Code".
Highlights from Hal's presentation follow:
(i) DCE 1.1 doc structure ...
o Intro to DCE
o Core Command/Admin:
- Command Reference
- Admin Guide Vol 1: Introduction
Vol 2: Core Services
o Extended Services Command/Admin
- DFS Admin Guide and Reference
- GDS Admin Guide and Reference
o Problem Determination Guide
o Programming
- App Dev Reference
- App Dev Guide Vol 1: Introduction and Style Guide
Vol 2: Core Services
Vol 3: Directory Services
(ii) Overall Status
o All new technology is documented
o No book had a full book editorial review (editorial review
continues at Prentice-Hall)
o No book had a full book technical review (all new text had at
least one technical review).
o Did not fix all "non-critical" CRs
- approx 50 CRs (defects, enhancements) deferred to 1.2
- approx 15 editorial CRs will be fixed at Prentice-Hall
- approx 74 CRs verified but not closed
o Index work is very uneven
o Some cross references are out of date
o No work was done to make documents convert cleanly to SGML
o Some PostScript figures do not print properly in some
circumstances
(iii) Book-by-book 1.1 Status and 1.2 Requirements ...
o ADMIN GUIDE:
*1.1* *1.2*
Vol 1 - Reflects new and changed - Convert to "Installation &
functionality Configuration" volume
- Eliminated old Ch 2 as - Move materials from Ch 1,3,
redundant with Intro book 4,6 to Vol 2
Vol 2 - New materials on dcecp,dced - Convert from "Core Comp'ts"
- Converted component sections to true "Core Svcs" book
to use dcecp and dced - Integrate Vol 1 materials
- New technologies added - Focus on consistency
- Improve task-orientation
o APP DEV GUIDE:
*1.1* *1.2*
Vol 1 - Intro based on old DevGd - Additional naming conventions
- Style part nearly all new - General improvements
- Emphasis on DCE prog'ng
considerations; based on
an example program
Vol 2 - Materials on new technologies - Remove redundant materials
- Corrected to use dcecp, dced - General improvements
- Non-trivial RPC revisions - Improve consistency
- Make AES conformant
Vol 3 - Reflects new technology - General improvements
- Major CRs fixed - Improve consistency
- Make AES conformant
o REFERENCE DOCS:
*1.1* *1.2*
- All commands in single - Eliminate obsolete commands
Command Ref volume - Re-org into single linear doc
- AppDevRef lacks permuted index - Improve consistency of ref
- All new commands, APIs are pages between components
documented - Debug switch information
- Obsolescent commands contain
"caveat" notes
o PROBLEM DETERMINATION GUIDE
*1.1* *1.2*
- better than feared, worse - add troubleshooting info
than hoped - improve messages
- 700pp, >3000 msgs, 2 indexes - DFS msg documentation
- no DFS - hypertext links from function,
- SEC messages not fully commands, guides ???
documented
- does not contain trouble-
shooting section
(iv) Tool Status ...
o DTE, OT, OSF DTD, TPT available as "Freeware":
ftp grabbag.osf.org
login: osfdtd
passwd: osf8879
cd osfdtd
(anonymous FTP planned for near future)
o 1.2 Status - no plans for tool maintenance or support under PST
- tool choice is up to PDC/Prime Contractor
(v) Technical Publication Toolkit Contents ...
o General purpose documentation converter technology
o Table driven
o Currently converts: - SML to OSFDTD
- OSFDTD to nroff/troff/SML
- OSFDTD to HTML
- OSFDTD to LaTex
o Used to generate docs shipped with NMO GA, Motif, and DCE 1.1
o Uses SGMLS parser and publicly available LaTex to PS converter
_______________________
3. PRENTICE-HALL UPDATE
Greg Doench gave an update on the plans for publishing the DCE 1.1
books. Following are the highlights:
o P-H successfully accommodated several licensees by printing/stocking
limited numbers of the 1.0.3 doc set. For 1.1, P-H will have more
flexibility to meet licensees' requirements thanks to the re-organized
library.
o Availability of 1.1 docs will be staged based on individual book
stability; target is to have all books available by end of 1Q95.
o Final editing, indexing etc. continues at P-H until published.
o DCE 1.2 doc starting point will be the P-H final/published source.
Greg welcomes any input from licensees regarding anticipated volume
requirements, availability requirements. Once P-H and OSF has worked
out the details of the 1.1 publishing plan, Greg will distribute its
highlights to sig-doc@osf.org and solicit input and feedback.
________________________
4. DCE 1.2 Documentation
Mickey Mann is the DCE 1.2 documentation team lead from the prime
contractor, IBM Austin.
At the time of our meeting, no DCE 1.2 doc plan existed. Many
content issues for 1.2 were noted by Hal's earlier presentation.
On more of the logistical side, it quickly became clear that
the audience of our meeting was not correct to produce results.
An action item was taken to quickly set up a meeting or conference
call between all 1.2 doc providers, Mickey and Ken Flowers.
It was apparent that a number of issues need to be resolved before
year-end: DTD usage, source format for 1.2 (format provided to IBM,
*and* format released to licensees), conversion tools, staffing.
Mickey welcomes your input to the 1.2 doc plan. What have been
issues/concerns in the past that we can fix now? What needs to be
changed? (process/content/tools) Mickey's e-mail is
mickmann@vnet.ibm.com
__________________________
5. Overview of PST Process
Ken Flowers gave his overview presentation of the PST Process (same
pitch as he gave during the 11/1 General Session). Highlights are
as follows (details are available directly from Ken; flowers@osf.org):
o What is a PST?
- Pre-Structured Technology
- Framework for joint development projects
- Like an RFT during implementation
- Technology selection done externally
- Initiated externally or internally
o Phases of a PST
- Authoring Phase
- Approval Phase
- Funding Phase
- Development Phase
- Distribution & Support Phase
Discussion followed re: SIGs' (and in particular Doc) relationship/role
with the PST process. It is clear that the Working Groups' role is an
important one, and consists of *formally* feeding requirements and
reviewing requirements for PST candidates. There will likely be a
coordinated effort at the DCE SIG level to feed DCE requirements via RFC
to the DCE PST. Our Working Group has a real opportunity to make a
difference.
An accepted problem with the PST process is that there is no
notification mechanism in place today to inform SIGs and WGs when
a PST is being formed.
Ken suggested four valuable roles for the DocSIG and/or the DCE doc WG:
1. Define, document requirements
2. Review documentation architecture and plans; define information
architecture for the future
3. Review delivery mechanisms (eg. help system, printed hardcopy)
4. Define areas for potential PSTs -- DTD
-- doc tools
-- conversion technologies
______________________________________
6. Election/Nomination of New WG Chair
Mike Leandertz is moving on to other (non-DCE) responsibilities and
stepped down as Chair of the DCE doc Working Group. It was agreed
that the group should continue, primarily to focus its efforts on
feeding requirements to the DCE PST.
The Group's new Chair is JANE WYMAN from Tandem Computers. Even
though Jane wasn't at the meeting ;-) she volunteered for the role
via her peer from Tandem, Kathy Digan. Jane is a long-time member
and contributor to our group; you can reach her at WYMAN_JANE@tandem.com
-------------------- End of Minutes -------------------------------
I have enjoyed working with everyone over the years, especially in
the last year as working group chair. I think these are exciting
times ahead for the group, and I encourage all of you to participate
and make a difference in the development of better and better
documentation.
I wish you all much success!
... Mike
==================================================================
Regards,
M.E. Leandertz
Manager, Information Development
IBM Software Solutions Toronto Laboratory
leandertz@vnet.ibm.com (416) 448-3501
==================================================================
