Design standards
Jump to navigation
Jump to search
Document Engineering Standard
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
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
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
<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
| 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
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)
After the header and version history, every document must contain these sections in order:
4.1 Table of Contents
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
## 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
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
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
- 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
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
- 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
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
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
<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: Cobol and PostgreSQL