Re: Help! What Should I Expect For Documentation?
From: Ä <shedges_at_hhhh.freeserve.co.uk>
Date: Sat, 5 Jun 1999 12:08:37 +0100
Message-ID: <7jb0c6$bvo$1_at_news4.svr.pol.co.uk>
Date: Sat, 5 Jun 1999 12:08:37 +0100
Message-ID: <7jb0c6$bvo$1_at_news4.svr.pol.co.uk>
Content-Type: text/plain;
charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
Scott,
=20
This is a nasty one! I've been involved before in negotiation (with =
contractors supplying us with Developer based system). The most =
problematic thing is the word 'Description'. Imagine you have table =
named 'Car', below are two possible descriptions:
"1. Car.=20
A Car.
2. Car
An automobile. For the purposes of this system, a Car is a normal =
family car, but excludes station wagons, mini-buses etc. It also =
excludes electrically power vehicle, but includes Motorcycles with an =
engine capacity of over 500cc. This table holds only a list of types of =
Car. To look at how individual cars are recorded within this system, =
see the 'cars_owned' table.
See also the 'Truck' table."
See the difference? Your supplier will want to give you version 1 and = will claim to have fulfilled the requirement to provide descriptions, = while you will want to receive something akin to version 2.
I would suggest that you include, in some kind of addendum, and example = of the documentation of a small data model (e.g. emp, dept etc), and = refer to that in the main document. Perhaps something along the lines = of=20
"All Descritpions and other documentation are to be full, and sufficient = in and of itself to provide and proper description of the system, such = as to enable the system to be maintained and extended in the future. = Example documentation is included at Annex A, and documentation to at = least this level is to be provided for the entire system"
This will take you some time to do, but without it, you haven't a prayer = of getting what you want, unless your suppliers are really nice people! = It will also help your designers know what you are talking about. Be = prepared to negotiate - they may not actually have all the information, = and may not be able to recover it (e.g. a list of every person who has = modified the code). =20
Things were relatively easy for us, because we had Designer/2000 and so = did they, and we specified exactly which bits of Designer we wanted = documented, and we created checklists for all the items and held a = formal audit of the documentation. It still wasn't entirely = satsifactory!
Ask for an electronic version of all documentation, as well as printed = versions. Eg an export of the the Designer/2000 application or = database.
I've also put other comments in Italics & capitals within your original = message below.
I hope this helps,
Simon Hedges
Gloucester
UK
- Original Message -----=20 From: scott=20 Newsgroups: comp.databases.oracle.tools Sent: 05 June 1999 03:00 Subject: Help! What Should I Expect For Documentation?
Are there any detailed standards for how to prepare documentation for = projects that include the following components:
a.. Oracle Forms;=20
b.. Oracle database;=20
c.. Pro*C code;=20
d.. daemons in several languages; and,=20
e.. 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:
=20
-------------------------------------------------------------------------=
---
SCHEDULE LICENSE B
ADDENDUM A
=20
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.
Specify that the documentation must be up to date. A lot of =
documentation suffers from development drift - columns get added and =
programs tweaked without the documentation being updated.
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.
OPTIONALITY. SNAPSHOTS. ROLES AND PRIVEGES. SYNONYMS, =
TABLESPACES. DBA REQUIREMENTS.
=20
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. (how many =
diagrams? How clearly laid out? Any rules regarding layout (e.g. 'No =
Dead Crows', minimum relationship line crossing).
Do you really want an ER digram, or do you want a Data =
Diagram? The two are different in Designer/2000, and the Data Diagram =
is much more useful in maintenance.
=20
q Include tables, primary and foreign key =
designations, and all database relationships (indicating one-to-one, =
one-to-many, many-to-many, et al).
(you can derive this from Designer by Reverse Engineering, =
so you can afford to be generous in negotiation if you have Designer =
yourselves - however, you will need all related descriptions)
=20
Control Logic
q Pertains to programs, which include but are not =
limited to procedures, functions, scripts, packages, daemons, forms and =
reports. TRIGGERS. CODE LIBRARIES, MENUS, OBJECT LIBRARIES, PACKAGES.
q Deliver as a separate Word document for each =
program. Use the following naming convention:
[name of program]_[program revision date].doc
PROGRAM VERSION NUMBER.
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. (the =
above will take them ages to document, if they don't have it recorded. =
You can look at the code itself to find this out. An area to be =
negotiated down EXCEPT for any SQL accesses which are dynamically =
constructed.
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.
=20
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.
=20
------=_NextPart_000_00A1_01BEAF4C.2456DBC0
Content-Type: text/html;
charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
[Quoted] <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META content=3D"text/html; charset=3Diso-8859-1" =
http-equiv=3DContent-Type>
<META content=3D"MSHTML 5.00.2014.210" name=3DGENERATOR>
<STYLE></STYLE>
</HEAD>
<BODY bgColor=3D#c0c0c0>
<DIV>
<DIV><FONT size=3D3>Scott,</FONT></DIV>
<DIV><FONT size=3D3></FONT> </DIV>
<DIV><FONT size=3D3>This is a nasty one! I've been involved before =
in=20
negotiation (with contractors supplying us with Developer based =
system). =20
The most problematic thing is the word 'Description'. Imagine you=20
have table named 'Car', below are two possible =
descriptions:</FONT></DIV>
<DIV> </DIV>
<DIV>"1. Car. </DIV>
<DIV>A Car.</DIV>
<DIV> </DIV>
<DIV>2. Car</DIV>
<DIV>An automobile. For the purposes of this system, a Car is a =
normal=20
family car, but excludes station wagons, mini-buses etc. It also =
excludes=20
electrically power vehicle, but includes Motorcycles with an engine =
capacity of=20
over 500cc. This table holds only a list of types of Car. To =
look at=20
how individual cars are recorded within this system, see the =
'cars_owned'=20
table.</DIV>
<DIV> </DIV>
<DIV>See also the 'Truck' table."</DIV>
<DIV> </DIV>
<DIV>See the difference? Your supplier will want to give you =
version 1 and=20
will claim to have fulfilled the requirement to provide descriptions, =
while you=20
will want to receive something akin to version 2.</DIV>
<DIV> </DIV>
<DIV>I would suggest that you include, in some kind of addendum, and =
example of=20
the documentation of a small data model (e.g. emp, dept etc), and refer =
to that=20
in the main document. Perhaps something along the lines of </DIV>
<DIV> </DIV>
<DIV>"All Descritpions and other documentation are to be full, and =
sufficient in=20
and of itself to provide and proper description of the system, such as =
to enable=20
the system to be maintained and extended in the future. Example=20
documentation is included at Annex A, and documentation to at least this =
level=20
is to be provided for the entire system"</DIV>
<DIV> </DIV>
<DIV>This will take you some time to do, but without it, you haven't a =
prayer of=20
getting what you want, unless your suppliers are really nice =
people! It=20
will also help your designers know what you are talking about. Be =
prepared=20
to negotiate - they may not actually have all the information, and may =
not be=20
able to recover it (e.g. a list of every person who has modified the=20
code). </DIV>
<DIV> </DIV>
<DIV>Things were relatively easy for us, because we had Designer/2000 =
and so did=20
they, and we specified exactly which bits of Designer we wanted =
documented, and=20
we created checklists for all the items and held a formal audit of the=20
documentation. It still wasn't entirely satsifactory!</DIV>
<DIV> </DIV>
<DIV>Ask for an electronic version of all documentation, as well as =
printed=20
versions. Eg an export of the the Designer/2000 application or=20
database.</DIV>
<DIV> </DIV>
<DIV>I've also put other comments in Italics & capitals within your =
original=20
message below.</DIV>
<DIV> </DIV>
<DIV> </DIV>
<DIV> </DIV>
<DIV> </DIV>
<DIV>I hope this helps,</DIV>
<DIV> </DIV>
<DIV>Simon Hedges</DIV>
<DIV>Gloucester</DIV>
<DIV>UK</DIV>
<DIV> </DIV>
<DIV> </DIV>
<BLOCKQUOTE=20
style=3D"BORDER-LEFT: #000000 2px solid; MARGIN-LEFT: 5px; MARGIN-RIGHT: =
0px; PADDING-LEFT: 5px; PADDING-RIGHT: 0px">
<DIV style=3D"FONT: 10pt arial">----- Original Message ----- </DIV>
<DIV=20
style=3D"BACKGROUND: #e4e4e4; FONT: 10pt arial; font-color: =
black"><B>From:</B>=20
<A href=3D"mailto:scott_at_nightowl.com" =
title=3Dscott_at_nightowl.com>scott</A> </DIV>
<DIV style=3D"FONT: 10pt arial"><B>Newsgroups:</B>=20
comp.databases.oracle.tools</DIV>
<DIV style=3D"FONT: 10pt arial"><B>Sent:</B> 05 June 1999 03:00</DIV>
<DIV style=3D"FONT: 10pt arial"><B>Subject:</B> Help! What Should I =
Expect For=20
Documentation?</DIV>
<DIV><BR></DIV>
<DIV><FONT size=3D4>Are there any detailed standards for how to =
prepare=20
documentation for projects that include the following=20
components:</FONT></DIV>
<UL style=3D"MARGIN-RIGHT: 0px">
<UL>
<LI><FONT size=3D4>Oracle Forms;</FONT>=20
<LI><FONT size=3D4>Oracle database;</FONT>=20
<LI><FONT size=3D4>Pro*C code;</FONT>=20
<LI><FONT size=3D4>daemons in several languages;</FONT><FONT =
size=3D4>=20
and,</FONT>=20
<LI><FONT size=3D4>other pieces?</FONT></LI></UL></UL>
<DIV> </DIV>
<DIV><FONT size=3D4>I am working with a vendor that has (in my =
opinion) a=20
misguided software development methodology. They =
have implemented a=20
substantial Oracle project. It has flaws; but, it is a good=20
product. We have worked with them for the past 2 years, =
helping=20
them with the requirement specification and testing their product as =
we use=20
it. In return, we have received a discount for the product; =
and,=20
now we are negotiating rights to the "documented" code in =
order to=20
implement our own systems that tie into the project. They are =
balking at=20
what my staff feels is fair documentation of their product's =
code. =20
We are caught up in some definitions of the appropriate =
documentation. =20
For those with experience with this sort of project or negotiation, =
please=20
advise!</FONT></DIV>
<DIV> </DIV>
<DIV><FONT size=3D4>Here are the definitions of some of the components =
in our=20
licensing schedule currently under negotiation:</FONT></DIV>
<BLOCKQUOTE style=3D"MARGIN-RIGHT: 0px">
<DIV><FONT size=3D4> =20
<H1 align=3Dcenter style=3D"TEXT-ALIGN: center">
<HR>
<B style=3D"mso-bidi-font-weight: normal">SCHEDULE LICENSE =
B<?xml:namespace=20
prefix =3D o ns =3D "urn:schemas-microsoft-com:office:office"=20
/><o:p></o:p></B></H1>
<H1 align=3Dcenter style=3D"TEXT-ALIGN: center"><B=20
style=3D"mso-bidi-font-weight: normal">ADDENDUM =
A<o:p></o:p></B></H1>
<P class=3DMsoNormal><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: =
10.0pt"> <o:p></o:p></SPAN></P>
<P class=3DMsoNormal><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">The following=20
definitions have been supplied to supplement this License in order =
to=20
clearly explain the expected deliverables for these documentation =
objects:=20
<I style=3D"mso-bidi-font-style: normal">Data Definitions; Entity =
Relationship=20
Diagrams;</I> <I style=3D"mso-bidi-font-style: normal">Control =
Logic;</I> <I=20
style=3D"mso-bidi-font-style: normal">Memoranda Describing Use;</I> =
and, <I=20
style=3D"mso-bidi-font-style: normal">Memoranda Describing=20
Application</I>.<SPAN style=3D"mso-spacerun: yes"> =
</SPAN>These=20
definitions contain the documentation deliverables, format for the=20
documentation and descriptions of its preparation.</SPAN></P>
<P class=3DMsoNormal><FONT size=3D1><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt"><EM>Specify =
that the=20
documentation must be up to date. A lot of documentation =
suffers from=20
development drift - columns get added and programs tweaked without =
the=20
documentation being updated.</EM></SPAN></FONT></P>
<H2><U>Data Definitions</U></H2>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1in; TEXT-INDENT: -0.5in; mso-list: l1 level1 =
lfo1; tab-stops: list 1.0in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">Deliver in a =
Microsoft=20
Excel document.</SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1in; TEXT-INDENT: -0.5in; mso-list: l1 level1 =
lfo1; tab-stops: list 1.0in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">Include =
descriptions of=20
all tables, views, sequences, indexes, constraints, triggers, =
columns,=20
column descriptions, primary keys and foreign keys.<SPAN=20
style=3D"mso-spacerun: yes"> </SPAN>Additionally, all columns =
should=20
indicate data type and data size.</SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1in; TEXT-INDENT: -0.5in; mso-list: l1 level1 =
lfo1; tab-stops: list 1.0in"><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: =
10.0pt"><o:p> =20
OPTIONALITY. SNAPSHOTS. ROLES AND=20
PRIVEGES. SYNONYMS, TABLESPACES. DBA=20
REQUIREMENTS.</o:p></SPAN></P>
<P class=3DMsoNormal><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: =
10.0pt"> <o:p></o:p></SPAN></P>
<H2><U>Entity Relationship Diagrams</U></H2>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1in; TEXT-INDENT: -0.5in; mso-list: l0 level1 =
lfo2; tab-stops: list 1.0in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">Deliver in an=20
industry-standard, entity-relationship diagram tool format – =
for example,=20
Oracle Designer 2000 – or as a Universal Modeling Language =
document. =20
<EM>(how many diagrams? How clearly laid out? Any rules=20
regarding layout (e.g. 'No Dead Crows', minimum relationship line=20
crossing).</EM></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1in; TEXT-INDENT: -0.5in; mso-list: l0 level1 =
lfo2; tab-stops: list 1.0in"><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: =
10.0pt"><EM> =20
Do you really want an ER digram, or do you want a =
Data=20
Diagram? The two are different in Designer/2000, and the Data =
Diagram=20
is much more useful in maintenance.</EM></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1in; TEXT-INDENT: -0.5in; mso-list: l0 level1 =
lfo2; tab-stops: list 1.0in"><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt"><FONT=20
=
size=3D1> &nbs=
p; </FONT></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1in; TEXT-INDENT: -0.5in; mso-list: l0 level1 =
lfo2; tab-stops: list 1.0in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">Include =
tables, primary=20
and foreign key designations, and all database relationships =
(indicating=20
one-to-one, one-to-many, many-to-many, et al).</SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1in; TEXT-INDENT: -0.5in; mso-list: l0 level1 =
lfo2; tab-stops: list 1.0in"><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: =
10.0pt"><o:p> =20
(<EM>you can derive this from Designer by Reverse =
Engineering, so you can afford to be generous in negotiation if you =
have=20
Designer yourselves - however, you will need all related=20
descriptions)</EM></o:p></SPAN></P>
<P class=3DMsoNormal><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: =
10.0pt"> <o:p></o:p></SPAN></P>
<H1><FONT size=3D5><U>Control Logic<o:p></o:p></U></FONT></H1>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1in; TEXT-INDENT: -0.5in; mso-list: l2 level1 =
lfo3; tab-stops: list 1.0in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">Pertains to =
programs,=20
which include but are not limited to procedures, functions, scripts, =
packages, daemons, forms and reports. TRIGGERS. CODE =
LIBRARIES,=20
MENUS, OBJECT LIBRARIES, PACKAGES.</SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1in; TEXT-INDENT: -0.5in; mso-list: l2 level1 =
lfo3; tab-stops: list 1.0in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">Deliver as a =
separate=20
Word document for each program.<SPAN style=3D"mso-spacerun: =
yes"> =20
</SPAN>Use the following naming convention:<o:p></o:p></SPAN></P>
<P class=3DMsoNormal style=3D"MARGIN-LEFT: 1in"><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt"><SPAN=20
style=3D"mso-spacerun: yes"> </SPAN>[name of =
program]_[program revision date].doc</SPAN></P>
<P class=3DMsoNormal style=3D"MARGIN-LEFT: 1in"><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: =
10.0pt"><o:p> =20
PROGRAM VERSION NUMBER.</o:p></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1in; TEXT-INDENT: -0.5in; mso-list: l2 level1 =
lfo3; tab-stops: list 1.0in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: =
10.0pt">Each=20
program should contain the following sections:<o:p></o:p></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1.5in; TEXT-INDENT: -0.5in; mso-list: l2 =
level1 lfo3; tab-stops: list 1.5in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: =
10.0pt">Name=20
of programmer<o:p></o:p></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1.5in; TEXT-INDENT: -0.5in; mso-list: l2 =
level1 lfo3; tab-stops: list 1.5in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">Creation=20
Date<o:p></o:p></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1.5in; TEXT-INDENT: -0.5in; mso-list: l2 =
level1 lfo3; tab-stops: list 1.5in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">Input/Output =
Variables:=20
name; data types and size; description of use.<o:p></o:p></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1.5in; TEXT-INDENT: -0.5in; mso-list: l2 =
level1 lfo3; tab-stops: list 1.5in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">Hardcoded =
database=20
objects used by the program.<SPAN style=3D"mso-spacerun: yes"> =
</SPAN>Columns should be specified when referring to tables and =
views. =20
<EM>(the above will take them ages to document, if they don't have =
it=20
recorded. You can look at the code itself to find this out. An =
area to=20
be negotiated down EXCEPT for any SQL accesses which are dynamically =
constructed.</EM></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1.5in; TEXT-INDENT: -0.5in; mso-list: l2 =
level1 lfo3; tab-stops: list 1.5in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">Functional =
dependencies=20
– note programs called from within the program code as well as =
programs=20
called independently from the code.<o:p></o:p></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1.5in; TEXT-INDENT: -0.5in; mso-list: l2 =
level1 lfo3; tab-stops: list 1.5in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">(Global) =
Variable=20
Dependencies<o:p></o:p></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1.5in; TEXT-INDENT: -0.5in; mso-list: l2 =
level1 lfo3; tab-stops: list 1.5in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">Written =
description of=20
how a program functions and what a program =
does.<o:p></o:p></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1.5in; TEXT-INDENT: -0.5in; mso-list: l2 =
level1 lfo3; tab-stops: list 1.5in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">Modification=20
Section:<o:p></o:p></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 2in; TEXT-INDENT: -0.5in; mso-list: l2 level1 =
lfo3; tab-stops: list 2.0in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">Re-state any =
part of the=20
above documentation pertinent to modifications made to a =
program.<SPAN=20
style=3D"mso-spacerun: yes"> </SPAN>Always include =
modifier’s name,=20
modification date and description of =
modification.<o:p></o:p></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 2in; TEXT-INDENT: -0.5in; mso-list: l2 level1 =
lfo3; tab-stops: list 2.0in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: =
10.0pt">Add=20
a modification section for each modification made.<SPAN=20
style=3D"mso-spacerun: yes"> </SPAN>Do not delete or change =
any prior=20
documentation.<o:p></o:p></SPAN></P>
<P class=3DMsoNormal><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: =
10.0pt"> </SPAN><FONT=20
size=3D5><U>Memoranda Describing Use<o:p></o:p></U></FONT></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1in; TEXT-INDENT: -0.5in; mso-list: l4 level1 =
lfo4; tab-stops: list 1.0in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: =
10.0pt">All=20
programs requiring interaction with a Daybreak user or administrator =
will=20
require documentation clearly explaining step-by-step instructions =
on its=20
use.<o:p></o:p></SPAN></P>
<P class=3DMsoNormal><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: =
10.0pt"> <o:p></o:p></SPAN></P>
<H2><U>Memoranda Describing Application</U></H2>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1in; TEXT-INDENT: -0.5in; mso-list: l3 level1 =
lfo5; tab-stops: list 1.0in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: =
10.0pt">All=20
requirements, both internal and external, for Daybreak to run and =
how to=20
meet these requirements.<o:p></o:p></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1in; TEXT-INDENT: -0.5in; mso-list: l3 level1 =
lfo5; tab-stops: list 1.0in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">Direction for =
installing=20
and configuring the hardware and software components of the Daybreak =
product.<o:p></o:p></SPAN></P>
<P class=3DMsoNormal=20
style=3D"MARGIN-LEFT: 1in; TEXT-INDENT: -0.5in; mso-list: l3 level1 =
lfo5; tab-stops: list 1.0in"><SPAN=20
style=3D"FONT-FAMILY: Wingdings; FONT-SIZE: 12pt; =
mso-bidi-font-size: 10.0pt">q<SPAN=20
style=3D"FONT: 7pt 'Times New =
Roman'">  =
; =20
</SPAN></SPAN><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: 10.0pt">Listing of all =
supported=20
optional configurations for the Daybreak product – e.g. a =
listing of all=20
supported fax server programs.<o:p></o:p></SPAN></P>
<P class=3DMsoNormal><SPAN=20
style=3D"FONT-SIZE: 16pt; mso-bidi-font-size: =
10.0pt"> <o:p></o:p></SPAN></P></FONT></DIV></BLOCKQUOTE></BLOCKQUOT=
E><FONT=20
size=3D4></DIV></FONT></BODY></HTML>
------=_NextPart_000_00A1_01BEAF4C.2456DBC0--
Received on Sat Jun 05 1999 - 13:08:37 CEST