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
Line 1: Line 1:
# Document Index
<span id="document-engineering-standard"></span>
= Document Engineering Standard =


## Architecture Decision Records (ADR)
'''Document ID:''' STD-DOC-001<br />
### File: `04_architecture_decision_records.mediawiki`
'''Applies to:''' All design-level and program-level specification documents in the pgcobol set<br />
- **Purpose**: Captures significant design decisions and their consequences.
'''Version:''' 1.0<br />
- **Format**: Follows the MADR format, a lightweight standard for documenting architectural decisions.
'''Status:''' Approved<br />
- **Contents**:
'''Owner:''' Lead Developer / Architect
- ADR template
- Specific decisions (e.g., Three-Tier Architecture)


## Test Traceability Matrix (TTM)
### File: `05_test_traceability_matrix.mediawiki`
- **Purpose**: Tracks the relationship between requirements and test cases.
- **Contents**:
- TC-NFT-002 — Performance: divider lookup query plan
- TC-NFT-003 — Reliability: graceful DB failure mid-run


## Non-Functional Requirements (NFR)
-----
### File: `03_non_functional_requirements.mediawiki`
- **Purpose**: Specifies quality attributes of the system.
- **Taxonomy**: Uses ISO/IEC 25010:2011 (SQuaRE) model.
- **Contents**:
- Categories: Performance, Reliability, Security, etc.


## Business Requirements Document (BRD)
<span id="purpose"></span>
### File: `07_brd_pgcbl-brd-001.mediawiki`
== 1. Purpose ==
- **Purpose**: Defines business requirements and scope.
- **Audience**: Business analysts, QA engineers, stakeholders.
- **Contents**:
- Assumptions and dependencies
- Out of Scope items
- Open issues (e.g., FR-01: generate loop commented out)


## Naming Coding Standard
This standard defines the mandatory scaffolding, metadata blocks, and governance structure that every document in this specification set must carry. It exists so that:
### File: `06_naming_coding_standard.mediawiki`
- **Purpose**: Standards for source file conventions.
- **Status**:
- Version: 1.0
- Approved and baselined.


## Scope and Applicability (SAD)
* Documents can be located, versioned, and audited independently of their content.
### File: `02_scope_and_applicability.mediawiki`
* Reviewers know immediately who owns the document, what it covers, and whether it is current.
- **Purpose**: Defines the document set and its navigation.
* The set as a whole is traceable — each document can be linked to requirements, decisions, and tests.
- **Related Documents**:
- Links to other documents in the set.


## Technical Specification Document (TSD)
### File: `01_technical_specification.mediawiki`
- **Purpose**: Implements system requirements.
- **Assumptions**: See PGCBL-SAD-002 for full register.


## Assumptions and Dependencies Register
-----
### File: `08_assumptions_and_dependencies_register.mediawiki`
- **Contents**:
- Key assumptions and dependencies (e.g., A-01, C-01)


## Test Case Catalogue
<span id="mandatory-document-header"></span>
### File: `05_test_traceability_matrix.mediawiki`
== 2. Mandatory Document Header ==
- **Purpose**: Catalogues test cases linked to requirements.
- **Status**: Includes planned tests requiring fixes.


## Out of Scope Items
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.
### File: `07_brd_pgcbl-brd-001.mediawiki`
- **Contents**:
- Exclusions from the system's functionality.


## Open Issues and Defects
<pre class="markdown"># &lt;Document Title&gt;
### File: `09_open_issues_and_defects.mediawiki`
- **Contents**:
- Known issues (e.g., OI-01, D-01)
- Targets and owners


## Cross-References
| Field | Value |
- **Related Documents**: Each document references others in the set, such as SAD, NFR, TSD, ADR, and TTM.
|--------------------|--------------------------------------------|
| 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 ===


## Revision History
<pre>&lt;PROJ&gt; - &lt;TYPE&gt; - &lt;NNN&gt;
- **Version Control**: Not explicitly detailed in provided context.

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]]

Revision as of 13:55, 25 March 2026

  1. Document Index
    1. Architecture Decision Records (ADR)
      1. File: `04_architecture_decision_records.mediawiki`

- **Purpose**: Captures significant design decisions and their consequences. - **Format**: Follows the MADR format, a lightweight standard for documenting architectural decisions. - **Contents**: 

 - ADR template
 - Specific decisions (e.g., Three-Tier Architecture)
    1. Test Traceability Matrix (TTM)
      1. File: `05_test_traceability_matrix.mediawiki`

- **Purpose**: Tracks the relationship between requirements and test cases. - **Contents**: 

 - TC-NFT-002 — Performance: divider lookup query plan
 - TC-NFT-003 — Reliability: graceful DB failure mid-run
    1. Non-Functional Requirements (NFR)
      1. File: `03_non_functional_requirements.mediawiki`

- **Purpose**: Specifies quality attributes of the system. - **Taxonomy**: Uses ISO/IEC 25010:2011 (SQuaRE) model. - **Contents**: 

 - Categories: Performance, Reliability, Security, etc.
    1. Business Requirements Document (BRD)
      1. File: `07_brd_pgcbl-brd-001.mediawiki`

- **Purpose**: Defines business requirements and scope. - **Audience**: Business analysts, QA engineers, stakeholders. - **Contents**: 

 - Assumptions and dependencies
 - Out of Scope items
 - Open issues (e.g., FR-01: generate loop commented out)
    1. Naming Coding Standard
      1. File: `06_naming_coding_standard.mediawiki`

- **Purpose**: Standards for source file conventions. - **Status**: 

 - Version: 1.0
 - Approved and baselined.
    1. Scope and Applicability (SAD)
      1. File: `02_scope_and_applicability.mediawiki`

- **Purpose**: Defines the document set and its navigation. - **Related Documents**: 

 - Links to other documents in the set.
    1. Technical Specification Document (TSD)
      1. File: `01_technical_specification.mediawiki`

- **Purpose**: Implements system requirements. - **Assumptions**: See PGCBL-SAD-002 for full register.

    1. Assumptions and Dependencies Register
      1. File: `08_assumptions_and_dependencies_register.mediawiki`

- **Contents**: 

 - Key assumptions and dependencies (e.g., A-01, C-01)
    1. Test Case Catalogue
      1. File: `05_test_traceability_matrix.mediawiki`

- **Purpose**: Catalogues test cases linked to requirements. - **Status**: Includes planned tests requiring fixes.

    1. Out of Scope Items
      1. File: `07_brd_pgcbl-brd-001.mediawiki`

- **Contents**: 

 - Exclusions from the system's functionality.
    1. Open Issues and Defects
      1. File: `09_open_issues_and_defects.mediawiki`

- **Contents**: 

 - Known issues (e.g., OI-01, D-01)
 - Targets and owners
    1. Cross-References

- **Related Documents**: Each document references others in the set, such as SAD, NFR, TSD, ADR, and TTM.

    1. Revision History

- **Version Control**: Not explicitly detailed in provided context.

Terug naar: Cobol and PostgreSQL

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