Design standards: Difference between revisions

From Webhuis wiki
Jump to navigation Jump to search
(Created page with "<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 do...")
 
No edit summary
 
(7 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Index of Document Engineering and System Requirements =
<span id="document-engineering-standard"></span>
= Document Engineering Standard =


'''Document ID:''' STD-DOC-001<br />
# [[Document Engineering]]
# [[Scope and applicability]]
'''Applies to:''' All design-level and program-level specification documents in the pgcobol set<br />
# [[Assumptions and Dependencies]]
'''Version:''' 1.0<br />
# [[Architecture decision records]]
'''Status:''' Approved<br />
# [[Non-Functional Requirements]]
'''Owner:''' Lead Developer / Architect
# [[Test Traceability Matrix]]
# [[Naming and Coding Standards]]
# [[Business Requirement Document]]
== Cross-Document References]]
; Document ID | Title | Relationship
|---|---|---
| PGCBL-SAD-001 | Scope and Applicability | Navigation Guide
| PGCBL-NFR-001 | Non-Functional Requirements | Quality Attributes Complement
| PGCBL-TSD-001 | Technical Specification | Implementation Details
| PGCBL-TTM-001 | Test Traceability Matrix | Test Case Mapping
| PGCBL-ADD-001 | Architecture Decision Records | Design Documentation


This index provides a structured overview of the document set, facilitating easy navigation and understanding of the interrelated components.

-----

<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/>
<hr/>
Terug naar: [[Cobol and PostgreSQL]]
Terug naar: [[Cobol and PostgreSQL]]

Latest revision as of 15:33, 25 March 2026

Index of Document Engineering and System Requirements[edit]

  1. Document Engineering
  2. Scope and applicability
  3. Assumptions and Dependencies
  4. Architecture decision records
  5. Non-Functional Requirements
  6. Test Traceability Matrix
  7. Naming and Coding Standards
  8. Business Requirement Document

== Cross-Document References]]

Document ID | Title | Relationship

|---|---|--- | PGCBL-SAD-001 | Scope and Applicability | Navigation Guide | PGCBL-NFR-001 | Non-Functional Requirements | Quality Attributes Complement | PGCBL-TSD-001 | Technical Specification | Implementation Details | PGCBL-TTM-001 | Test Traceability Matrix | Test Case Mapping | PGCBL-ADD-001 | Architecture Decision Records | Design Documentation

This index provides a structured overview of the document set, facilitating easy navigation and understanding of the interrelated components.

Terug naar: Cobol and PostgreSQL

Retrieved from "https://wiki.webhuis.nl:443/index.php?title=Design_standards&oldid=4755"