DLPS Documentation: Overview

updated 2005-11-22 by khage

Definition

This document defines the current state of DLPS documentation and how it is to be maintained. All DLPS documentation is assumed to be public, except in special cases. Not included here is project planning, including specifications, project plans, etc., which (because it is restricted, specific to the project itself, and of temporary value) is managed separately. Documentation, in this context, is defined as any public document, guide or set of instructions governing either internal DLPS practice or recommended/required practices for DLPS products (e.g., DLXS). These documents are intended to be generic, rather than (as with project planning) specific to one task with a finite term. They are also, we hope, of longer term value than documentation specific to a project. Of course there are exceptions to this, as well, e.g., EEBO with its projected 5 year term.

Process management and organization

A while ago, the Journal Management System was abandoned as a method for maintaining DLPS and DLXS documentation since the server serving the XML-based documentation using a particular, and aging, XML delivery system (Cocoon) was being retired. In order to keep the documentation up and running in a simpler form for the near- and mid-term, it was decided to use HTML. The conversion from XML documents to HTML documents was accomplished. However, there might be a few formatting or stylistic changes that will require some hand-editing. That will be accomplished in the months ahead whenever editing is done on these documents.

  1. Documents are created and edited by DLPS staff in /l1/web/d/dlps/docs on the development machine (clamato).
  2. Files are then indexed using a shell script that indexes the documentation using swish-e.
  3. Occasionally, someone (pagliere, jweise, etc.) using some tool such as Dreamweaver, can check files for consistency (i.e., broken links, HTML validity, orphaned files, etc.)
  4. Whenever appropriate, the files aremoved to the production machine via rdist.

Basic document rules

  1. In order to keep obstacles to documentation maintenance as low as possible, the only requirements, other than accuracy of content, are that files produced be valid HTML and have working links.
  2. Writers should attempt to keep up to date with the documentation's content, keep track of author and update date information in META tags, use the dlpsdocs.css styles when possible.
  3. File naming: Files currently have names left over from the days of the Journal Management System's need for flat directory structures. Now that directory structures can follow depth and naming conventions that have more to do with the logical / conceptual relationships of the documents themselves, file and directory names will probably undergo some changes in the near- to mid-term. Dreamweaver can be helpful here since it can update links when file names or directories are changed.