Home -> Usenet -> c.d.o.tools -> Help! What Should I Expect For Documentation?

Help! What Should I Expect For Documentation?

From: scott <scott_at_nightowl.com>
Date: Fri, 4 Jun 1999 21:00:49 -0500
Message-ID: <Nx%53.506$A4.2157_at_news1.iquest.net> 









Are there any detailed standards for how to prepare 
documentation for projects that include the following 
components:


    
  
      
    
    • Oracle Forms;
      • 
    
    • Oracle database;
      • 
    
    • Pro*C code;
      • 
    
    • daemons in several languages; 
    and,
      • 
    
    • other pieces?


 


I am working with a vendor that has (in my opinion) a 
misguided software development methodology.  They have implemented a 
substantial Oracle project.  It has flaws; but, it is a good product.  
We have worked with them for the past 2 years, helping them with the 
requirement specification and testing their product as we use it.  In 
return, we have received a discount for the product; and, now we 
are negotiating rights to the "documented" code in order to implement 
our own systems that tie into the project.  They are balking at what my 
staff feels is fair documentation of their product's code.  We are 
caught up in some definitions of the appropriate documentation.  For those 
with experience with this sort of project or negotiation, please 
advise!


 


Here are the definitions of some of the components in our 
licensing schedule currently under negotiation:



  
 
  

  

  SCHEDULE LICENSE B

  
ADDENDUM A

  
 

  
The following definitions 
  have been supplied to supplement this License in order to clearly explain the 
  expected deliverables for these documentation objects: Data Definitions; Entity Relationship 
  Diagrams; Control Logic; Memoranda Describing Use; and, Memoranda Describing Application.  These definitions contain the 
  documentation deliverables, format for the documentation and descriptions of 
  its preparation.

  
 

  
Data Definitions

  
q                 
  Deliver in a Microsoft 
  Excel document.

  
q                 
  Include descriptions of 
  all tables, views, sequences, indexes, constraints, triggers, columns, column 
  descriptions, primary keys and foreign keys.  Additionally, all columns should 
  indicate data type and data size.

  
 

  
Entity Relationship Diagrams

  
q                 
  Deliver in an 
  industry-standard, entity-relationship diagram tool format – for example, 
  Oracle Designer 2000 – or as a Universal Modeling Language 
  document.

  
q                 
  Include tables, primary 
  and foreign key designations, and all database relationships (indicating 
  one-to-one, one-to-many, many-to-many, et al).

  
 

  
Control Logic

  
q                 
  Pertains to programs, 
  which include but are not limited to procedures, functions, scripts, packages, 
  daemons, forms and reports.

  
q                 
  Deliver as a separate Word 
  document for each program.  Use 
  the following naming convention:

  
     [name of 
  program]_[program revision date].doc

  
q                 
  Each 
  program should contain the following sections:

  
q                 
  Name 
  of programmer

  
q                 
  Creation 
  Date

  
q                 
  Input/Output Variables: 
  name; data types and size; description of use.

  
q                 
  Hardcoded database objects 
  used by the program.  Columns 
  should be specified when referring to tables and views.

  
q                 
  Functional dependencies – 
  note programs called from within the program code as well as programs called 
  independently from the code.

  
q                 
  (Global) Variable 
  Dependencies

  
q                 
  Written description of how 
  a program functions and what a program does.

  
q                 
  Modification 
  Section:

  
q                 
  Re-state any part of the 
  above documentation pertinent to modifications made to a program.  Always include modifier’s name, 
  modification date and description of modification.

  
q                 
  Add a 
  modification section for each modification made.  Do not delete or change any prior 
  documentation.

  
 

  
Memoranda Describing Use

  
q                 
  All 
  programs requiring interaction with a Daybreak user or administrator will 
  require documentation clearly explaining step-by-step instructions on its 
  use.

  
 

  
Memoranda Describing Application

  
q                 
  All 
  requirements, both internal and external, for Daybreak to run and how to meet 
  these requirements.

  
q                 
  Direction for installing 
  and configuring the hardware and software components of the Daybreak 
  product.

  
q                 
  Listing of all supported 
  optional configurations for the Daybreak product – e.g. a listing of all 
  supported fax server programs.

  
 

Received on Sat Jun 05 1999 - 04:00:49 CEST












Original text of this message