dbis_docs/DOCUMENTATION_STANDARDS.md

DBIS DOCUMENTATION STANDARDS

Standards and Guidelines for All DBIS Documentation

---

DOCUMENT METADATA

Version: 1.0
Last Updated: 2024-01-15
Effective Date: 2024-01-15
Status: Active
Authority: DBIS Executive Directorate

---

DATE FORMAT STANDARDS

Standard Date Format

All dates in DBIS documentation shall use the ISO 8601 format: YYYY-MM-DD

Examples:

• Correct: 2024-01-15
• Incorrect: January 15, 2024, 01/15/2024, 15-01-2024

Date Usage Guidelines

• Document Creation Dates: Use actual date of document creation
• Effective Dates: Use date when document becomes effective
• Last Updated Dates: Use date of most recent revision
• Signature Dates: Use date of execution/signature

Placeholder Dates

When actual dates are not yet determined:

• Use format: [YYYY-MM-DD - To be determined]
• Or: [Date to be specified]
• Update with actual dates before final publication

---

VERSION CONTROL STANDARDS

Version Numbering

Use Semantic Versioning (SemVer) format: MAJOR.MINOR.PATCH

• MAJOR: Breaking changes or major revisions
• MINOR: New features, additions, non-breaking changes
• PATCH: Bug fixes, corrections, minor updates

Examples:

• 1.0.0 - Initial version
• 1.1.0 - Added new section
• 1.1.1 - Fixed typo, corrected reference
• 2.0.0 - Major restructuring

Document Status

• Draft: Work in progress, not yet approved
• Active: Approved and in effect
• Superseded: Replaced by newer version
• Archived: No longer in use, retained for historical reference

---

FORMATTING GUIDELINES

Document Structure

1. Title: Level 1 heading (#)
2. Subtitle/Description: Level 2 heading (##)
3. Major Sections: Level 2 or 3 headings (## or ###)
4. Subsections: Level 3 or 4 headings (### or ####)

Headers and Sections

• Use consistent heading hierarchy
• Include horizontal rules (---) between major sections
• Number sections where appropriate (e.g., Section 1.1, Section 1.2)

Lists

• Use bullet points (-) for unordered lists
• Use numbered lists (1.) for sequential procedures
• Use nested lists for sub-items

Emphasis

• Bold for key terms, document names, important concepts
• Italic for emphasis, foreign terms, or citations
• Code for technical terms, code snippets, file paths

---

NAMING CONVENTIONS

File Naming

• Use descriptive names with underscores: Document_Name.md
• Use title case for document names
• Include version numbers in filename only for archived versions: Document_v1.0.md

Directory Structure

• Use numbered prefixes for ordered categories: 01_category/
• Use lowercase with underscores for directory names
• Maintain consistent structure across all categories

---

CROSS-REFERENCE STANDARDS

Internal Document References

Format: [Document Title](relative/path/to/document.md)

Examples (Note: These are example formats, not actual links):

• [Title VI: Cyber-Sovereignty](02_statutory_code/Title_VI_Cyber_Sovereignty.md) - ✅ Valid example
• [CSP-1113 Technical Specification](csp_1113/CSP-1113_Technical_Specification.md) - ✅ Valid example
• [Document Title](relative/path/to/document.md) - ⚠️ Example format only

Section References

Format: [Section Name](document.md#section-name)

Examples (Note: These are example formats, not actual links):

• [Section 1.1: Server Standards](11_technical_specs/Technical_Standards.md#section-11-server-standards) - ⚠️ Example format only
• [Section Name](document.md#section-name) - ⚠️ Example format only

Anchor-Only Links

Format: [Section Name](#anchor-name)

Guidance:

• Use for navigation within the same document
• Anchor names should match heading IDs (lowercase, hyphens for spaces)
• HTML anchor tags: <a id="anchor-name"></a> can be used for custom anchors
• Markdown headings automatically create anchors (lowercase, spaces to hyphens)

Example:

• [Go to Section](#section-name) - Links to heading "## Section Name" in same document

Directory Links

Format: [Directory Name](path/to/directory/)

Guidance:

• Use when linking to a directory of related documents
• Consider linking to a README.md or index file if available
• Directory links are valid but may be flagged by verification scripts
• Prefer specific file links when possible

Example:

• [Operational Examples](08_operational/examples/) - Links to examples directory

Related Documents Section

All major documents shall include a "Related Documents" section at the end listing:

• Related statutory code titles
• Referenced technical specifications
• Supporting operational documents

---

CONTENT STANDARDS

Language and Tone

• Use formal, professional language
• Write in third person for official documents
• Use active voice where possible
• Avoid ambiguous terms; be specific

Terminology

• Use consistent terminology throughout all documents
• Define acronyms on first use: Digital Banking and Institutional System (DBIS)
• Refer to Glossary for standard definitions

Placeholder Content

• Avoid generic placeholders like "As established" or "As specified"
• Provide specific values or references to where values are established
• Use [To be determined] only when absolutely necessary

---

REVIEW AND APPROVAL PROCESS

Document Review

1. Technical Review: By relevant technical department
2. Legal Review: By legal department for legal documents
3. Compliance Review: By compliance department
4. Executive Review: By Executive Directorate for major documents

Approval Authority

• Constitutional Documents: Sovereign Control Council (SCC)
• Statutory Code: SCC approval required
• Technical Specifications: Technical Department with Executive Directorate approval
• Operational Procedures: Executive Directorate approval

Change Management

• All changes tracked in revision history
• Major changes require re-approval
• Version number updated with each change
• Change log maintained in document

---

DOCUMENT METADATA TEMPLATE

All documents shall include a metadata section at the beginning:

## DOCUMENT METADATA
**Version:** 1.0
**Last Updated:** YYYY-MM-DD
**Effective Date:** YYYY-MM-DD
**Status:** Active
**Authority:** [Relevant Department or Council]

---

REVISION HISTORY TEMPLATE

Major documents shall include a revision history section:

## REVISION HISTORY
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | YYYY-MM-DD | [Author] | Initial version |

---

END OF DOCUMENT MARKER

All documents shall end with:

**END OF [DOCUMENT NAME]**

---

END OF DOCUMENTATION STANDARDS