Fw: [chairs] latest draft of doc mgmt system requirements

[Diane Jordan <drj@us.ibm.com>]

Hi,
Thought some of you might have comments
on this plan.  It would probably be polite to roll them up to one
reply for Karl - if you want to send them to me I will consolidate (without
any editing). 
Thanks.
Regards, Diane
IBM  Dynamic e-business Technologies
drj@us.ibm.com
(919)254-7221 or 8-444-7221, Mobile: 919-624-5123

----- Forwarded by Diane
Jordan/Raleigh/IBM on 02/27/2004 05:38 PM -----

"Karl F. Best" <karl.best@oasis-open.org>

02/25/2004 01:26 PM

Please respond to
karl.best

To	Chairs OASIS <chairs@lists.oasis-open.org>
cc	jeff.lomas@oasis-open.org
Subject	[chairs] latest draft of doc mgmt system requirements

Chairs:

Attached is the latest draft of the doc mgmt system requirements, which
I hope adequately takes into account the many fine comments and 
suggestions that you provided last week. Further comment always welcome.
Jeff and I will start work on creating a system design based on these 
requirements.

(Provided in text format as suggested by Norm :-)

-Karl



OASIS DocMgmt Functional Requirements
(25 February 2004)

First Phase
--------------
* General description: A simple, open collaborative document development
environment (sandbox) for members of TCs and SCs to jointly develop 
specifications and other documents in a free-form environment.
    - Probably Wiki?  (Twiki? MoinMoin?)
    - Separate area for each TC and SC

* Documents viewable only to TC members. Access control based on Kavi 
database; only TC members (and SysAdmin) may access this area

* Ability to merge changes from multiple people into a single doc

Transition
--------------
* OASIS will need to provide guidelines/criteria for when docs may or 
must advance to the next phase (the controlled repository)

Second Phase
--------------
* General Description: A controlled document management/versioning 
environment; a repository providing storage/management of files created
by TCs, SCs,  and other OASIS groups
    - Probably based on CVS with customized interface (WebCVS?
WebDAV? 
Subversion? TortoiseCVS?)
    - All documents are permanently archived (only Admin has
delete rights)
    - All documents are publicly viewable, downloadable

* Data structure
    - A separate area in the repository for each TC/SC/group
    - Both default and definable hierarchy within each TC area;
default 
folders for “drafts”, “minutes”, “press”, “contributions”, etc.
(TBD) TC 
chair/editor has ability to create additional folders (Restricted to NN
levels?)
    - Document metadata (filename, title, date, description,
creator, 
language, associated files,  etc.) stored in XML(?) (Depending on
capabilities of engine e.g. CVS). Metadata schema is TBD and needs to be
editable over time by SysAdmin. Should include at least one free form 
field definable by the TC.

* User interface
    - Repository has a web interface for uploading and tree browsing,
searching, and retrieval. Support for all major browsers. Intuitive UI
should require little or no user documentation.
    - Repository has command line interface for power users;
this 
interface will have the same access control and restrictions on 
permissible actions, etc. as the web interface.
    - Search/retrieval
       - Files may be found via search and by tree browsing
       - Search by any of the metadata fields
       - Full-text search of contents (except for binary
formats)
       - Listing of single files in browsing and search
results includes 
the metadata fields. The listing for packages includes the list of 
single files in the package, then drill down for information on those files.

* Persistent URLs
    - At file creation (first checkin) the document is assigned
a URL by 
the creator. The URL must be predictable in advance of checkin. URL in
the form of e.g. http://docs.oasis-open.org/<tcname>/<dir>/<filename>
where <filename> corresponds to the OASIS file naming scheme including
the version but without the revision number. (The URL would not include
the revision level but the filename would.)
    - The assigned URL will always resolve to the latest revision
of the 
document, regardless of the document’s (revisioned) filename; the URL
will identify a specification throughout its entire lifetime from 
working draft to OASIS Standard. (This implies that the person checking
in the file must be able to specify the old file that this new one is 
replacing.)
    - Previous revisions of the document will be accessible via
a 
variant of the URL containing the revision number.
    - (Version number is for versions of the specification, e.g
v1 is 
approved as an OASIS Standard after which work on v2 is started. Each 
version will go through a number of revisions during its lifetime, e.g.
.01, .02, ... .99. See the OASIS filenaming spec.)

* Multiple file types supported
    - Any type of file may be uploaded (not restricted to e.g.
just .doc 
or .htm).
    - TCs must be able to store both source (e.g. MSWord, XML,
or HTML) 
and compiled (e.g. PDF) versions of each file. The repository should 
have some means to connect two different files (e.g. foo3.htm and 
foo3.pdf are different representations of the same file); the user can
upload and associate all formats in a single operation. Search results
should show all available formats of the same file and the user should
be able to select/retrieve one or all.
    - HTML files may include graphics which will be stored with
the file 
(use relative URLs?)
    - (CVS functionality will not be the same for binary/proprietary
files as for text-based formats, i.e. it cannot provide the same 
functionality for a .doc as for an .xml file. Functionality for diff, 
merge, change logs, etc. not available. The TC will have to decide which
format is best for them based on the capabilities they require.)

* Packages
    - A specification may be composed of multiple documents.
A “package” 
is a collection of related files (e.g. chapters in a book or parts of a
modular schema or DTD). The various parts can be the same or different
file types.
    - The package file is an HTML file (similar to a ToC) created
by the 
TC with links to and metadata for the various components. (OASIS will 
need to define a format/syntax/template for this package file.)
    - The package is updated by editing the links in the package
file. 
Each of the components are maintained by editing it individually. Each
component, as well as the package file, has its own revision number, but
the entire set would collectively have a version number.
    - The entire “package” may be uploaded or downloaded in
a single 
operation. Individual documents in the package may also be uploaded or
downloaded.
    - Support for chapters or parts of a multi-part document
(with links 
between parts); a package could have a ToC with links to the individual
files
    - Support for modular DTDs (e.g. DocBook)
    - The entire “package” is addressable via a single URL
pointing to 
the package file which in turn links to the individual files in the package.

* Security
    - Access control: check-in/out based on Kavi user authentication;
different permissions for public, TC members, chair/secretary/editor, etc.
    - Public has read rights for all documents
    - TC members have read rights
    - TC Chair, Secretary, and Editor have create, edit rights
for 
folders and create and checkin/out rights for documents in their 
respective TC area
    - Admin has admin rights (create, checkin/out, modify, delete
of all 
folders and files)

* Kavi integration
    - Kavi user acct/pswd used for authentication
    - Notification to the Kavi group when a document is uploaded
(similar to current Kavi notification)
    - Links to the interface of the current Kavi doc repository
are 
redirected to the new doc mgmt system (i.e. interface to the Kavi doc 
repository is no longer the default, this one “drops in” to replace it).
    - Docs currently in the Kavi repository will continue to
be 
addressable and viewable by their Kavi URL. The Kavi listing and 
searching functions may still be accessed by users, but won’t be the 
default. (Current docs in the Kavi repository are allowed to stay where
they're at until the TC wants to move them.)

* Localizable interface, with localization to occur in a later phase

Later phase functionality
---------------------------
* File naming automation: Naming and versioning of documents follows 
OASIS file naming scheme; when a new document is created automated helps
(pulldowns for each of the segments of the filename) will appear to help
the user to create/assign a conformant name and retain uniqueness.

* Localized interface (priority for which languages TBD)

* Count/traffic report of downloads (e.g. how many people have 
downloaded a particular doc?)

* File validation (schema parsing) upon checkin

* Publishing (convert to PDF or HTML) upon checkin