Document Engineering Standard[edit]

Document ID: STD-DOC-001
Applies to: All design-level and program-level specification documents in the pgcobol set
Version: 1.0
Status: Approved
Owner: Lead Developer / Architect

1. Purpose[edit]

This standard defines the mandatory scaffolding, metadata blocks, and governance structure that every document in this specification set must carry. It exists so that:

Documents can be located, versioned, and audited independently of their content.
Reviewers know immediately who owns the document, what it covers, and whether it is current.
The set as a whole is traceable — each document can be linked to requirements, decisions, and tests.

2. Mandatory Document Header[edit]

Every document must open with the following block before any content section. Fields marked [R] are required; fields marked [O] are optional but strongly recommended.

# <Document Title>

| Field              | Value                                      |
|--------------------|--------------------------------------------|
| Document ID        | <PROJ>-<TYPE>-<NNN>          [R]           |
| Document Type      | <full type name>             [R]           |
| System / Project   | <system name and version>    [R]           |
| Version            | <major.minor>                [R]           |
| Status             | Draft | Review | Approved | Superseded [R] |
| Owner              | <name, role>                 [R]           |
| Author(s)          | <name(s)>                    [R]           |
| Reviewers          | <name, role — one per row>   [O]           |
| Approved by        | <name, role, date>           [O]           |
| Created            | YYYY-MM-DD                   [R]           |
| Last modified      | YYYY-MM-DD                   [R]           |
| Classification     | Internal | Confidential | Public [R]  |
| Parent document    | <Document ID of parent, if any> [O]        |
| Supersedes         | <Document ID this replaces, if any> [O]    |

2.1 Document ID Scheme[edit]

<PROJ> - <TYPE> - <NNN>

PROJ   Two-to-six letter project code          e.g. PGCBL
TYPE   Document type code (see §2.2)           e.g. BRD
NNN    Zero-padded sequence within type        e.g. 001

Examples:
  PGCBL-BRD-001   Business Requirements Document #1
  PGCBL-TSD-001   Technical Specification #1
  PGCBL-ADD-001   Architecture Decision Document #1
  PGCBL-TTM-001   Test Traceability Matrix #1

2.2 Document Type Codes[edit]

Code	Full Name	Abbrev used in filenames
BRD	Business Requirements Document	brd
TSD	Technical Specification Document	tsd
DDD	Data Dictionary Document	ddd
FLD	Flow Diagram Document	fld
PLG	Program Logic Guide	plg
BRG	Business Rules Guide	brg
IOB	I/O Behaviour Document	iob
CFD	Control Flow Document	cfd
ADD	Architecture Decision Document	add
NFR	Non-Functional Requirements	nfr
SAD	Scope and Applicability Document	sad
TTM	Test Traceability Matrix	ttm
NCS	Naming and Coding Standard	ncs
DEP	Deployment Guide	dep
GLO	Glossary	glo

3. Mandatory Version History Table[edit]

Every document must carry a version history table immediately after the header block.

## Version History

| Version | Date       | Author       | Status   | Change Summary                    |
|---------|------------|--------------|----------|-----------------------------------|
| 0.1     | YYYY-MM-DD | <name>       | Draft    | Initial draft                     |
| 0.2     | YYYY-MM-DD | <name>       | Review   | Incorporated review comments      |
| 1.0     | YYYY-MM-DD | <name>       | Approved | Approved by <approver>            |
| 1.1     | YYYY-MM-DD | <name>       | Approved | <brief description of change>     |

Versioning rules:

0.x — draft iterations before first approval.
1.0 — first approved baseline.
1.x — minor corrections or additions that do not change approved scope.
x.0 (x > 1) — major revision requiring re-approval.
A superseded document retains its history; the new document references it in the header.

4. Mandatory Sections (all document types)[edit]

After the header and version history, every document must contain these sections in order:

4.1 Table of Contents[edit]

For documents longer than three sections, include a Markdown ToC:

## Table of Contents

1. [Purpose and Scope](#1-purpose-and-scope)
2. [Assumptions and Dependencies](#2-assumptions-and-dependencies)
3. [<content sections>](#...)
N. [Open Issues](#n-open-issues)

4.2 Purpose and Scope[edit]

## 1. Purpose and Scope

### 1.1 Purpose
<One paragraph: what this document is and why it exists.>

### 1.2 Scope
<What system version, components, and time period this document covers.>

### 1.3 Out of Scope
<Explicit list of what this document does NOT cover, to prevent misuse.>

### 1.4 Audience
<Who should read this document and what prior knowledge is assumed.>

### 1.5 Related Documents

| Document ID     | Title                        | Relationship         |
|-----------------|------------------------------|----------------------|
| PGCBL-BRD-001   | Business Requirements        | Parent requirements  |
| PGCBL-ADD-001   | Architecture Decisions       | Design rationale     |

4.3 Assumptions and Dependencies[edit]

See document PGCBL-SAD-001 for the full template. Minimum required inline:

## 2. Assumptions and Dependencies

### Assumptions
| ID    | Assumption                                           | Risk if wrong          |
|-------|------------------------------------------------------|------------------------|
| A-01  | <statement believed to be true, unverified>          | <consequence>          |

### Dependencies  
| ID    | Dependency                                           | Owner                  |
|-------|------------------------------------------------------|------------------------|
| D-01  | <something that must be in place before this works>  | <who provides it>      |

### Constraints
| ID    | Constraint                                           | Source                 |
|-------|------------------------------------------------------|------------------------|
| C-01  | <limit on the design space>                          | <requirement / policy> |

4.4 Open Issues[edit]

Every document must carry an open-issues section at the end, even if empty:

## N. Open Issues

| ID     | Issue                                | Owner    | Target date | Status |
|--------|--------------------------------------|----------|-------------|--------|
| OI-01  | <description>                        | <name>   | YYYY-MM-DD  | Open   |

5. Section Numbering Convention[edit]

Top-level sections: ## 1., ## 2., etc.
Subsections: ### 1.1, ### 1.2, #### 1.1.1 (max three levels).
Appendices: ## Appendix A —, ## Appendix B —.
Do not use letters for main sections; numbers only.

6. Table Formatting Convention[edit]

All tables use GFM (GitHub Flavoured Markdown) pipe syntax. Column alignment:

Left-align text columns.
Right-align numeric columns.
Use a header separator row with at least three dashes.

IDs in tables follow the pattern <TYPE>-<NN> where TYPE is a two-to-four letter mnemonic and NN is a zero-padded sequence (e.g. FR-01, BR-ALGO-03, A-01).

7. Code and Pseudocode Blocks[edit]

COBOL source extracts: use fenced code blocks with language hint cobol.
SQL: sql.
Pseudocode (language-neutral): no language hint, or text.
Shell commands: bash.
Mermaid diagrams: mermaid.

8. Cross-Reference Convention[edit]

When one document references content in another, use:

[<title>](<Document ID>) §<section>

Example: [Technical Specification](PGCBL-TSD-001) §3.2 means section 3.2 of the TSD.

9. Review and Approval Process[edit]

Author creates draft (v0.1)
        │
        ▼
Peer review — reviewer comments added as inline notes or GitHub/Jira issues
        │
        ▼
Author resolves comments, increments to v0.2 … v0.n
        │
        ▼
Owner sign-off → status changes to "Approved", version becomes 1.0
        │
        ▼
Document baselined in version control (git tag or DMS record)
        │
        ▼
Any change raises a new draft (v1.1-draft), repeat cycle

10. File Naming Convention[edit]

<proj>-<type>-<nnn>-<short-title>.md

Examples:
  pgcbl-brd-001-business-requirements.md
  pgcbl-tsd-001-technical-specification.md
  pgcbl-add-001-method-dispatch-pattern.md
  pgcbl-ncs-001-cobol-naming-standard.md

All lowercase, hyphens as separators, no spaces, .md extension.

Terug naar: Design standards | Cobol and PostgreSQL

Document Engineering