Documentation
These are personal notes. You are welcome to read them.
|
|
|
|
|
Management hints
|
HTML, javascript
|
Other
|
(best practises, risks, choosing software, ...)-
(scope, design, development, rollout)
-
(details on the scope and design phase)
-
-
|
|
|
| |
|
|
|
|
|
Contents
Various Specifications
Note: Final owner is the supporting organisation
|
Area
|
What is understood
|
| Functional Specifications |
Business requirements: scope document. It refers to the business requirements. |
| Design specifications |
Design documents |
| Production document for Application |
An overview of the system, similar to the "Introduction to CBS". |
| Design Review Specifications |
Define a formal process for changes during the design phase. |
| Program specifications |
Detailed documentation covering such topics as access to database, tables,
etc. Partially covered by: Administration Guide. |
| Test specifications |
Test strategy. Details of the testing plan for system, production acceptance,
functional, performance and end-to-end testing. |
| Data Modelling Specification |
A description of the data model. |
| User documentation |
User manual |
| Contract models |
Describe the interfaces between systems |
| System Administration |
- System Administration Checklist
- Database Backups
- System Backups
- Restart and Recovery
- Logging/Error Handling
- Application Administration
- Audit Trail
- Unix System Administration
- Configuration Management
- Scheduling
- Data Backup and Archiving
- Disaster Recovery
- Security Approach
Agile list:
- written for maintenance developers
- overview of the system’s architecture
- summary of requirements
- summary of design decisions
- references to the detailed architecture and models
|
| Operational documentation |
Information for writing the operational procedures (daily operations):
backups, generation of tapes, observing for critical process failures,
database thresholds, line availability, etc. The user documentation extended
with enough information so as to write the operational procedures (daily
operations). Other aspects should include information related with day
to day operations such as undertaking backups (full and partial), generation
of tapes, observing critical process failures, database thresholds, line
availability, etc. This would basically be an operator's handbook.
Knowing the top-level jobs is most important. It is fairly easy to follow the threads down into
each procedure or function that they call. However, if one job triggers another via a message
or other dependency, the triggered jobs should be listed as well.
In particular, for operations, each process should have:
- Job Description
- Severity Level of Job Abends (Automatically Sent to Helpdesk)
- How to control the job, how to know if the job has finished, how to
know if it has succeeded
- Typical error types and procedures to handle them
- Restart Procedures
- Documentation (Free Form)
- Job Controls
- Dependencies, interactions with other systems, databases, and files
- Backup procedures
- Troubleshooting guidelines
|
| Change Control Documentation |
Procedures for change request management, problem report management,
and delivery management. A project plan for the phases following User Acceptance
Test needs to be drawn up including the following:
- Define a Change Request Plan.
- Detail of change and overall impact to the organisation and to the application managers.
- Identify the potential risks to the organisation and how to address these.
- Summary of the change to Management.
|
| Configuration Management |
Current configuration and procedure for modifying the configurationThis
section covers the procedure for keeping track of the configuration of the
machines. |
| Desktop Configuration |
Hardware, systems software, datacomm, applicationSecurityCommunication |
| Host Configuration |
Hardware, systems software, datacomm, applicationSecurityCommunication |
| Development documentation |
- database object creation scripts
- Database schema
- How the tables are filled with data (data flow): source of data,
loading and transformation, description of processes
- How to use the tool
- Description of all interfaces (files, database views, ...)
- How to install / set-up the application
- Complete parameterisations, initialisation files (location and short
description of particularities)
- Application code sources: location, short description of sub-directories
- Non standard compilation requirements.
- Application code sources: location, short description of sub-directories.
Describe non standard compilation requirements.
- Parameters (input/output, data type, nulls/defaults allowed, potential errors, abnormal exits,
how to deal with abnormal situations, ...)
- For tables:
- Column name, allow nulls, data type, default value
- Indexes
- Security / grants (select, and insert/update/delete)
- Views
|
| Database documentation |
- Version information (main version and patches)
- Oracle-home (name and path)
- Machine, port number and sid / service name.
- Oracle-home of client
- Passwords for sys and system
|
Project plan
|
Application
|
|
| Functional Definition for Application |
Description of the executables (configuration, pictures, naming conventions,
critical processes) |
| Implementation |
Plan roll-out starting with the user acceptance testTime line, tasks,
people, Dependencies, Milestones, "Dry run", "Next Step" criteria (validation,
go/no go) |
| Procurement |
The actual procurement of the hardware and the software |
| Training |
An inventory is needed for the training that is necessary. However, we
still need to know who is staffed in the organisation in charge of the operations.For
the people using the system and the people supporting it.
- Skills needed
- Skill Available
- Gap analysis
- Proposed Action Plan
- Management overview for all training needed
- Application specific training
- Knowledge transfer
|
| Physical security |
|
| Logical security |
Logons, retries, disk access passwords, disk permissions |
| Capacity & Performance |
Define the possibilities for growth (growth path). Add a growth plan
for the database size (how should the database be incremented?) |
| Organisation |
A description of the organisation that will support the application. |
| Audit and Review Procedures |
High-level test cycles that verify that the system complies to the functional
specifications. This section contains high-level test cycles that verify
that the system complies to the functional specifications. These test scenarios
are used after each change of the system to verify functional compliance.
This section describes what should be done. The test cases are in "Test
Specifications". |
| Change Management Procedures |
How to manage changes in any one of the sections in this document |
| Disaster Recovery - Business Continuity |
- Availability practices: What makes it so that the application will
be as available as needed.
- Imagine disasters and define appropriate responses (fall-back plan
etc.).
- Define procedures to prevent disasters (backups, UPS, shadow disks,
...)
- Get a written statement indicating what type of disaster recovery
is needed. And if disaster recovery is needed, then to what level of
disaster.
|
Reports produced
deliverables for each change to production (EIC)
- A risk assessment .
- A communications plan is in place that notifies affected users of the pending
change.
- An acceptance test plan has been developed and executed.
- A contingency / back-out plan is in place.
- All system dependencies have been identified and tested.
Documentation
Documentation of an existing system:
- Network and telecommunications infrastructure
- Hardware, operating systems of servers and of clients (PCs)
- System architecture
- Interactions / interfaces with other systems
- Data model (the important part that should be potentially exported)
- Existing maintenance
- Existing support
Template for Document History:
- Original Date of Document
- Date of Last Modification
- Next Scheduled Revision Date
- Distribution
- Summary of Changes
- Approving Authority: (Title and Function approving the process)
- Document Owner and Custodian: (Title and Function of process owner responsible
for maintaining the process)
System Requirements
- 24x7 requirements
- Backup requirements, restore strategy
- Expected database and file sizes (initial / growth)
- External access requirements
- Communication methods: ODBC, SQL, DSN
- Security / permissions:
Deliverables to be produced by a data modeler according to Simsion [1]:
- A summary of the requirements
- Inputs to the data model: meeting minutes, inteview minutes, documentation
from the project, ...
- Conceptual model
- Entity class definitions, attribute lists and attribute definitions
- Constraints and business rules not mentionned above
- Logical data model, including notes about the decisions taken in the
translation from conceptual model
- List of cross-references between the logical model and the process model
to show that all processes are covered
- Physical data model, including notes about the decisions taken to translate from the
logical model.
Minimal documentation to be produced at the end of a project
by the database developers and Business Objects developers
so that the objects in the BO universe can be understood.
(The original list was created in Beverly...)
Data model:
- Names of tables
- Keys (primary keys and natural keys, i.e. the columns that serve to identify
specific rows)
- Foreign keys, whether enforced or not, and the table/column to which they
join up. This is especially important when the name of the foreign key does
not match the name of the primary key to which it joins.
- Cardinality of the joins
- A short explanation of what each table in the database holds (all data,
a sub-set, history or only current information, how far back in history...)
- A description - even just one sentence - of the differences between the
tables with similar names
The definition of each object in Business Objects:
- Text descrption of object and its business use
- associated terms (glossary)
- associated business rules
- SQL defintion (table and field)
- description of the appropriate joins between related tables (if foreign
keys are well documented above, this would not be necessary).
- eventual data profiling results
- location in BO folders
Other:
- Constraints due to architecture, technology, ...
- Business rules that apply across all use cases
- Non-functional requirements, i.e. requirements that are not "observable",
such as security, performance, standards, regulations,...
Some thoughts on documentation in agile environment
See Agile Documentation
Tests also serve as documentation of requirements. I think that requirements are important and need to be
captured on their own.
Model with others in a collaborative effort, ideally with several generalists. When people work alone,
they tend to make copies of the documentation from elsewhere.
This are the main things to document:
- critical information,
- design rationale: document the important and the non-obvious.
- requirements, including some specific use cases, edge cases, and exceptions
- usage procedures
- operational procedures, especially the top-level jobs
- don't describe the code but say where to find the code
- document the locations of the documentation
The idea is to minimize the information in the written documents
so that there is less to maintain, capturing the information in only
one place. Ideally, if several people work together, there is not the
temptation to copy over information from another document.
Work with the audience of the document, who will determine when
it is complete.
On the other hand, detailed project plans, detailed requirements specifications,
detailed design specifications are not agile.
Documentation in the code are less critical now that variables names are more descriptive.
Code comments explaining a design choice and why the developer is doing something are more
useful than a comment about how. Explain "tricks" and algorithms.
Comment for modifications with date and developer are useful too.
"Technical Specification Document"
Developers write the "Technical Specification Document" (TSD). It serves both as a short technical design document,
with an architectural diagram, and an operational document. It assumes that a "Functional Specification Document"
exists with requirements, a source to target mapping, or a screen layout, depending on the type of component.
The mains points of a TSD:
- Overview of the component
- An archtectural diagram
- A complete list of the top-level jobs, meaning the jobs that start the others. The called jobs
do not have to be necessarily listed. Triggered jobs do have to be listed if the triggering
job does not explicitely give the name of the dependent job.
- Inputs to and outputs from the component, including any interaction outside of the component
- Dependencies
- Rationale behind any major design decisions: document the important and the non-obvious.
- Description of jobs: schedule, error conditions, how to know if the job has succeeded,
what to do in case of failure, what to know about restarting,
- Can the job be restarted at any time, after a failure, or is a clean up of some sort needed?
- Typical error types and procedures to handle them
- Backup method
- Configuration and how to modify it
- Names and locations, such as job names, script names/path/server, database object names/schemas/database,
and location of source code. Any developer must be able to find the code without asking the
original developer where things are. The idea is not to describe the code but to describe
where to find the code.
Note that table descriptions, detailed code, or script content are NOT needed if they can be
simply extracted from the system if the name of the object is known. These extracts
can be put in an addendum, with the date of the extract. Ideally, a script could be created to extract this
information into a text file.
See also some thoughts on documentation in agile environment in the previous section.
The Project Plan
Project Plan Layout
- Executive Summary (Overview)
- Project Objectives
- Assumptions and Risks
- Milestones
- Work Breakdown Structure (see [2])
- Network Diagram
- Project Team
- Equipment, Materials and Supplies
- Budget
- Project Organization
- Operating Procedures
- Assessment and Review Standards
- Approvals
Who? (1) Myself and have it reviewed, (2) with key players, (3) break it into
sub-projects and assign to groups [2].
|
A project not worth doing
is not worth doing well
Jery Pournelle[2]
|
Features of a system:
Name of feature
- description of the need
- proposed solution
- benefit of solution (what it is useful for)
Terms and definitions
- [1] Simsion, Graeme C.; Witt, Graham C.: Data Modeling Essentials, Third Edition, 2005, Elsevier