|
Reusable/Shareable Documentation Task Force Summary Paper
1 Introduction
Digital's products are becoming more and more integrated.
Components of several products are being combined; in some
cases, one component may be used in several products. This
means that we may have several writers in different groups
preparing similar information. We need a process whereby
modules of information (text and art) can be reused by
writers. If the description of a particular product is
being used in several product documents, that description
should be the same. All writers who need that description
should be able to access the latest version.
Such a process will save Digital money; writers will be
focused on new functionality and usability. Writers are
not rewriting and modifying information that exists and
needs no changes. It also gives Digital consistency across
diverse products.
A common library of art and text shared across the
publications group shows our networking competency,
reflects consistency in the look of Digital's products,
is efficient, and saves money.
2 Resource List
One goal of the Reusable/Shareable Documentation task force
was to provide a resource list to make it easier for people
to find information that they need. This list is divided
into the following subject areas:
o Research
o Templates
o Clip Art
o Information
2.1 Research
Our group has already completed some research that might
help in reusing or sharing information. Some research
has been done as part of the Information Presentation
Architecture (IPA) and some has been completed as part
of project work or white papers.
1
2.1.1 IPA
Some of the IPA research might be useful for reusing and
sharing documentation. The following list describes some
relevant information.
o Authority List - A list of technical terms showing the
approved spelling, hyphenation, and capitalization
in current use. This document can be found in the
TNPUBS::PUBLIC$DISK:[PUBLIC.IPA]AUTHORITY_LIST.TXT file.
o Internationalization Plan - A description of interna-
tionalization policies that includes general guidelines
for producing documentation that can be translated
more easily. This document can be found in the
TNPUBS::PUBLIC$DISK:[PUBLIC.IPA.I18N]INTERNATIONALIZATION_
PLAN.PS file.
2.1.2 Multiplatform Documentation Strategy
The DECnet writing group incorporated a multiplatform
documentation strategy to help them reduce and manage
the number of books that had to be produced for multiple
releases on different platforms. The strategy can
be found in the TNPUBS::PUBLIC$DISK:[PUBLIC.DECNET_
OSI.EDITING]STRATEGY.PS file.
2.2 Templates
To make it easier to use different formatting tools,
templates for Interleaf and VAX DOCUMENT are available.
2.2.1 Interleaf Templates
The catalogs and templates are being revised. When
available, they can be found in the COMM cabinet.
2.2.2 VAX DOCUMENT RCC/HTO Template
The Reader's Comment and How-To-Order pages template is
available from the TNPUBS::DOC$LOCAL_TEMPLATES:RCPAGE_
TEMPLATE.SDML file.
2
2.2.3 VAX DOCUMENT Installation Guide Templates
The BOOKIE::PUBLIC:[PUBLIC] directory contains sample
installation guide templates for DEC OSF/1, SUN, and
OpenVMS operating systems. The following files might be
useful.
The sample files in this directory are some installation
guides that have been submitted to SSB.
2.3 Clip Art
If you want to create some rough art using clip art,
the clip art libraries for Interleaf and RAGS are in
the indicated locations. Clip art in different formats
(PostScript and for PCs) is available from the Digital Art
Library as indicated.
2.3.1 Interleaf Clip Art
Interleaf clip art is available in the clipart folder
located in the T&N Symbols drawer of the COMM cabinet.
2.3.2 RAGS Clip Art
RAGS clip art is available in the
SYS$COMMON:[SYSHLP.EXAMPLES.DOC_GRAPHICS] directory.
2.3.3 Digital Art Library
The Digital Art Library contains graphics from promotional
literature as well as product documentation. File
listings for the Digital Art Library are in the
NACIMT::ART$ROOT:[DOC]XXX-FILES-ON-CALDEC.LIS file, where
XXX is DEC, PC, or MAC.
2.4 Information
There is a lot of other information available that might
be useful in producing information for our products. For
example, sales and trademark information is available on
VTX.
3
2.4.1 Sales Information
The On-line Presentation Access Library (OPAL) Program has
been released on CD-ROM and contains current presentations
in PostScript and customizable PowerPoint files that are
accessible with DOS and VMS interfaces. In addition, it
contains clip art files from the Digital Art Library (see
Section 2.3.3).
PROMOLIT provides information sheets over the network.
You just type VTX PROMOLIT at the OpenVMS operating system
prompt and you can request PostScript or ASCII files.
2.4.2 Trademark Information
You can find the most recent information for Digital and
third-party trademarks by typing VTX LAW at the OpenVMS
operating system prompt. A menu lets you select the
information that you need.
3 Conclusion
With the limited time and resources that we had available,
this task force attempted to gather as much information
as possible in one place. However, even as this paper
summarizing our efforts was being written, a new
navigational tool for hypertext became available to
demonstrate that our goal of providing accessible text
and art for reuse in our information products is feasible.
The availability of the Digital Art Library (described in
Section 2.3.3) on the World Wide Web is an implementation
of part of our intended proposal when starting this task
force. The World Wide Web provides accessibility to
graphics in multiple formats from different sources with
a consistent interface. This tool substantiates the fact
that a common library of art and text shared across the
organization is an attainable goal that merits further
investigation.
4
|