Design standards - Revision history

Martin at 15:33, 25 March 2026

2026-03-25T15:33:49Z

← Older revision		Revision as of 15:33, 25 March 2026
Line 4:		Line 4:
	# [[Scope and applicability]]		# [[Scope and applicability]]
	# [[Assumptions and Dependencies]]		# [[Assumptions and Dependencies]]
			# [[Architecture decision records]]
	# [[Non-Functional Requirements]]		# [[Non-Functional Requirements]]
	# [[Test Traceability Matrix]]		# [[Test Traceability Matrix]]

Martin at 15:28, 25 March 2026

2026-03-25T15:28:44Z

← Older revision		Revision as of 15:28, 25 March 2026
Line 3:		Line 3:
	# [[Document Engineering]]		# [[Document Engineering]]
	# [[Scope and applicability]]		# [[Scope and applicability]]
	# Assumptions and Dependencies ==		# [[Assumptions and Dependencies]]
	# Non-Functional Requirements ==		# [[Non-Functional Requirements]]
	# Test Traceability Matrix ==		# [[Test Traceability Matrix]]
	# Naming and Coding Standards ==		# [[Naming and Coding Standards]]
	# Business Requirement Document ~~(BRD) ==~~		# [[Business Requirement Document]]
	== Cross-Document References ==		== Cross-Document References]]
	; Document ID \| Title \| Relationship		; Document ID \| Title \| Relationship
	\|---\|---\|---		\|---\|---\|---

Martin at 15:11, 25 March 2026

2026-03-25T15:11:19Z

← Older revision		Revision as of 15:11, 25 March 2026
Line 2:		Line 2:

	# [[Document Engineering]]		# [[Document Engineering]]
	# [[Scope and ~~Applicability~~]]		# [[Scope and applicability]]
	# Assumptions and Dependencies ==		# Assumptions and Dependencies ==
	# Non-Functional Requirements ==		# Non-Functional Requirements ==

Martin at 15:09, 25 March 2026

2026-03-25T15:09:46Z

@@ Line 1: / Line 1: @@
 = Index of Document Engineering and System Requirements =
-== 1. Document Engineering ==
+# [[Document Engineering]]
 == Cross-Document References ==
 ; Document ID | Title | Relationship

Martin: /* 2. Scope and Applicability */

2026-03-25T14:59:25Z

2. Scope and Applicability

← Older revision		Revision as of 14:59, 25 March 2026
Line 14:		Line 14:

	== 2. Scope and Applicability ==		== 2. Scope and Applicability ==
			[[Scope and applicability]]
	- [[System Version Identifier\|System Version Identifier]]		- [[System Version Identifier\|System Version Identifier]]
	- pgcobol — Prime Numbers Application v1.0		- pgcobol — Prime Numbers Application v1.0

Martin at 14:57, 25 March 2026

2026-03-25T14:57:49Z

← Older revision		Revision as of 14:57, 25 March 2026
Line 1:		Line 1:

	```mediawiki
	= Index of Document Engineering and System Requirements =		= Index of Document Engineering and System Requirements =

Line 78:		Line 76:

	This index provides a structured overview of the document set, facilitating easy navigation and understanding of the interrelated components.		This index provides a structured overview of the document set, facilitating easy navigation and understanding of the interrelated components.
	```
	<hr/>		<hr/>
	Terug naar: [[Cobol and PostgreSQL]]		Terug naar: [[Cobol and PostgreSQL]]

Martin at 14:55, 25 March 2026

2026-03-25T14:55:38Z

Show changes

Martin at 13:55, 25 March 2026

2026-03-25T13:55:38Z

Show changes

Martin: Created page with " = 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 do..."

2026-03-25T13:26:58Z

Created page with " = 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 do..."

New page

= 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.

<pre class="markdown"># <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] |</pre>

=== 2.1 Document ID Scheme ===

<pre><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</pre>

=== 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.

<pre class="markdown">## 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> |</pre>
'''Versioning rules:'''

* <code>0.x</code> — draft iterations before first approval.
* <code>1.0</code> — first approved baseline.
* <code>1.x</code> — minor corrections or additions that do not change approved scope.
* <code>x.0</code> (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:

<pre class="markdown">## 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)</pre>

=== 4.2 Purpose and Scope ===

<pre class="markdown">## 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 |</pre>

=== 4.3 Assumptions and Dependencies ===

See document <code>PGCBL-SAD-001</code> for the full template. Minimum required inline:

<pre class="markdown">## 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> |</pre>

=== 4.4 Open Issues ===

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

<pre class="markdown">## N. Open Issues

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

-----


== 5. Section Numbering Convention ==

* Top-level sections: <code>## 1.</code>, <code>## 2.</code>, etc.
* Subsections: <code>### 1.1</code>, <code>### 1.2</code>, <code>#### 1.1.1</code> (max three levels).
* Appendices: <code>## Appendix A —</code>, <code>## Appendix B —</code>.
* 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 <code><TYPE>-<NN></code> where TYPE is a two-to-four letter mnemonic and NN is a zero-padded sequence (e.g. <code>FR-01</code>, <code>BR-ALGO-03</code>, <code>A-01</code>).

-----


== 7. Code and Pseudocode Blocks ==

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

-----


== 8. Cross-Reference Convention ==

When one document references content in another, use:

<pre>[<title>](<Document ID>) §<section></pre>
Example: <code>[Technical Specification](PGCBL-TSD-001) §3.2</code> means section 3.2 of the TSD.

-----


== 9. Review and Approval Process ==

<pre>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</pre>

-----


== 10. File Naming Convention ==

<pre><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</pre>
All lowercase, hyphens as separators, no spaces, <code>.md</code> extension.
<hr/>
Terug naar: [[Cobol and PostgreSQL]]