Documentation, Governance Artifacts, and Runbook Completion

Why Documentation Is a Professional Obligation

A database system that exists only in the mind of the person who built it is a liability, not an asset. When that person is unavailable—due to illness, resignation, or reassignment—the organization loses the ability to operate, recover, or audit the system safely. Professional documentation transforms tacit knowledge into a shared, maintainable record. DAMA International's Data Management Body of Knowledge (DMBOK, 2nd edition) treats documentation as a core data governance responsibility, not an optional afterthought. In this lesson you will assemble the complete technical documentation package that a new DBA would need to take over your capstone system on day one.

The Data Dictionary

A data dictionary is the authoritative catalog of every table and column in your database. For each column you must record the business name (what the business calls the field, e.g., "Customer Email Address"), the technical name (the actual column name in the schema, e.g., `cust_email`), the data type (e.g., `VARCHAR(255)`), allowed values or domain (e.g., must match email format), the source system where the value originates, the designated data steward, and any regulatory classification such as Personally Identifiable Information (PII).

You cross-reference every entry against your Entity-Relationship Diagram (ERD). PostgreSQL's `information_schema.columns` view and the `pg_class` catalog table are useful starting points: they let you extract technical metadata programmatically rather than typing it by hand, reducing transcription errors. Use the instructor-provided template so that the format is consistent across all team submissions.

Identifying PII columns is not merely a documentation habit—it is the first step in protecting data subjects' privacy and complying with applicable regulations. Mark those columns clearly; downstream access control and masking decisions depend on them.

Data Quality Rules

Data quality rules define what "good" data looks like. You must write at least eight rules in two forms: plain English (so that a business analyst can understand the intent) and SQL (so that the database can enforce it). Common rule types include:

• NOT NULL constraints — mandatory fields must always contain a value.
• Referential integrity — a foreign key value must exist in the parent table.
• Range checks — numeric values must fall within a valid range (e.g., `quantity > 0`).
• Format validation — character patterns must match a defined format, enforced with a `CHECK` constraint or a trigger.

After writing the rules, run a data quality audit query against your live database. Compare actual data against each rule and document every violation in a defect log. Each defect log entry should identify the rule that was violated, the affected row or rows (by primary key), the nature of the defect, and its current resolution status (open, in progress, or resolved). This log becomes evidence that you actively govern the data, not just that you defined rules on paper.

The Lineage Diagram

Data lineage shows where data comes from and how it moves. Your lineage diagram must trace each data element from its source system through any transformation steps to the target table in your database. Use draw.io to create a clear flow diagram: boxes for systems and tables, arrows for data movement, and labels for any transformations applied (e.g., type casting, deduplication, concatenation). A well-drawn lineage diagram allows an auditor or a new DBA to answer the question "Where did this value come from?" in minutes rather than hours.

The Operational Runbook

A runbook is a step-by-step operations manual. Your runbook must cover five areas:

1. Daily startup and shutdown procedures — in what order services are started or stopped, and how to verify success.

2. Backup verification steps — how to confirm that a backup completed successfully and how to test restorability.

3. User provisioning workflow — the process for creating, modifying, and revoking database accounts and roles.

4. Incident response checklist — the sequence of actions to take when an alert fires or a service degrades.

5. Disaster recovery contact tree — who to call, in what order, when a major failure occurs.

Runbooks must be written at a level of detail that allows a competent but unfamiliar DBA to execute every procedure correctly without asking anyone for help. Avoid pronouns like "it" or "the system" when you mean a specific service or command—be explicit.

The Change Log

Every schema or configuration change made during the build phase must be recorded in the change log. Each entry should capture the date, the person who made the change, a description of what changed, the reason for the change, and whether the change was tested and approved. The change log creates an audit trail and is essential for troubleshooting regressions.

Safety and Integrity Considerations

Documentation work carries its own risks. Inaccurate documentation is sometimes more dangerous than no documentation, because a reader trusts it and acts on it. Verify every procedure in the runbook by actually executing it in a test environment before writing the final version. Protect the documentation package itself: store it in version-controlled storage with access controls, because it contains PII field locations and disaster recovery contacts that must not be exposed to unauthorized parties. Apply least-privilege principles to who can edit the documents.

Submitting Your Package

Your completed package will be scored against a 25-item rubric. Every SQL data quality rule must execute without error in your PostgreSQL environment before submission. A classmate acting as a new DBA will walk through your runbook in ten minutes during a peer review exercise—if they get lost, a section needs revision. Aim for a minimum rubric score of 80%.