Editing Document Engineering

<span id="document-engineering-standard"></span>
= Document Engineering Standard =

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


-----

<span id="purpose"></span>
== 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.


-----

<span id="mandatory-document-header"></span>
== 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"># &lt;Document Title&gt;

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

<pre>&lt;PROJ&gt; - &lt;TYPE&gt; - &lt;NNN&gt;

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>
<span id="document-type-codes"></span>
=== 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
|}


-----

<span id="mandatory-version-history-table"></span>
== 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 | &lt;name&gt;       | Draft    | Initial draft                     |
| 0.2     | YYYY-MM-DD | &lt;name&gt;       | Review   | Incorporated review comments      |
| 1.0     | YYYY-MM-DD | &lt;name&gt;       | Approved | Approved by &lt;approver&gt;            |
| 1.1     | YYYY-MM-DD | &lt;name&gt;       | Approved | &lt;brief description of change&gt;     |</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 &gt; 1) — major revision requiring re-approval.
* A superseded document retains its history; the new document references it in the header.


-----

<span id="mandatory-sections-all-document-types"></span>
== 4. Mandatory Sections (all document types) ==

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

<span id="table-of-contents"></span>
=== 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. [&lt;content sections&gt;](#...)
N. [Open Issues](#n-open-issues)</pre>
<span id="purpose-and-scope"></span>
=== 4.2 Purpose and Scope ===

<pre class="markdown">## 1. Purpose and Scope

### 1.1 Purpose
&lt;One paragraph: what this document is and why it exists.&gt;

### 1.2 Scope
&lt;What system version, components, and time period this document covers.&gt;

### 1.3 Out of Scope
&lt;Explicit list of what this document does NOT cover, to prevent misuse.&gt;

### 1.4 Audience
&lt;Who should read this document and what prior knowledge is assumed.&gt;

### 1.5 Related Documents

| Document ID     | Title                        | Relationship         |
|-----------------|------------------------------|----------------------|
| PGCBL-BRD-001   | Business Requirements        | Parent requirements  |
| PGCBL-ADD-001   | Architecture Decisions       | Design rationale     |</pre>
<span id="assumptions-and-dependencies"></span>
=== 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  | &lt;statement believed to be true, unverified&gt;          | &lt;consequence&gt;          |

### Dependencies  
| ID    | Dependency                                           | Owner                  |
|-------|------------------------------------------------------|------------------------|
| D-01  | &lt;something that must be in place before this works&gt;  | &lt;who provides it&gt;      |

### Constraints
| ID    | Constraint                                           | Source                 |
|-------|------------------------------------------------------|------------------------|
| C-01  | &lt;limit on the design space&gt;                          | &lt;requirement / policy&gt; |</pre>
<span id="open-issues"></span>
=== 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  | &lt;description&gt;                        | &lt;name&gt;   | YYYY-MM-DD  | Open   |</pre>

-----

<span id="section-numbering-convention"></span>
== 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.


-----

<span id="table-formatting-convention"></span>
== 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>&lt;TYPE&gt;-&lt;NN&gt;</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>).


-----

<span id="code-and-pseudocode-blocks"></span>
== 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>.


-----

<span id="cross-reference-convention"></span>
== 8. Cross-Reference Convention ==

When one document references content in another, use:

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


-----

<span id="review-and-approval-process"></span>
== 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 &quot;Approved&quot;, 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>

-----

<span id="file-naming-convention"></span>
== 10. File Naming Convention ==

<pre>&lt;proj&gt;-&lt;type&gt;-&lt;nnn&gt;-&lt;short-title&gt;.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: [[Design standards]] | [[Cobol and PostgreSQL]]