Skip to content

IGB-DOC-002

Documentation Style Guide

Document ID : IGB-DOC-002

Title : Documentation Style Guide

Version : v1.0

Status : Approved

Owner : IGB Engineering

Last Update : 2026-08

Revision History

Version Date Description
v1.0 2026-08 Initial Approved Release

1. Purpose

This document defines the official documentation style requirements for the IGB Engineering Platform.

Its purpose is to ensure that engineering documentation is consistent, readable, searchable, maintainable, and suitable for long-term engineering use.

This document defines document presentation and writing conventions.

It does not define the overall documentation architecture, document hierarchy, or repository structure.

2. Scope

This standard applies to engineering documentation maintained within the IGB Engineering Platform.

Including but not limited to:

  • Architecture
  • Engineering
  • Requirements
  • Communication
  • Security
  • Validation
  • Manufacturing
  • Software
  • Bill of Materials
  • Releases
  • Intellectual Property
  • Products
  • Specifications
  • Standards
  • Templates

3. Authority

This document is a subordinate documentation standard under:

IGB-DOC-001 — Documentation Architecture

IGB-DOC-001 defines the overall documentation architecture and authority.

This document defines documentation style requirements within that architecture.

Where a conflict exists between this document and IGB-DOC-001, IGB-DOC-001 shall take precedence.

4. Documentation Principles

Engineering documents shall be:

  • Clear
  • Precise
  • Consistent
  • Traceable
  • Machine Searchable
  • Human Readable
  • Version Controlled
  • Long-term Maintainable

Documentation shall describe engineering facts, decisions, requirements, implementation, verification, or controlled engineering information.

Ambiguous or undocumented assumptions shall be avoided.

5. Document Header

Official engineering documents shall provide document control information.

The recommended document header shall include:

  • Document ID
  • Title
  • Version
  • Status
  • Owner
  • Last Update

6. Document Title

The document title shall clearly identify the subject of the document.

Titles shall:

  • Be concise
  • Be technically meaningful
  • Avoid unnecessary abbreviations
  • Remain stable across revisions unless the document scope changes

The title shall correspond to the controlled Document ID.

7. Heading Hierarchy

Markdown headings shall use a consistent hierarchy.

Recommended structure:

# Document Title
# 1. Major Section
## 1.1 Subsection
## 1.2 Subsection
# 2. Major Section

Heading levels shall not be skipped without justification.

8. Paragraph Style

Technical statements shall be written as direct engineering statements.

Requirements, decisions, specifications, and observations shall use language appropriate to their engineering meaning.

9. Lists

Lists shall be used where multiple related items must be presented.

Ordered lists shall be used for procedures or explicitly sequenced activities.

10. Tables

Tables shall be used for structured information such as requirements, interfaces, parameters, revision history, status, ownership, traceability, and configuration data.

Tables shall use descriptive column names.

11. Code and Command Blocks

Shell commands, source code, configuration examples, and machine-readable data shall be presented using fenced code blocks.

Code blocks shall identify the appropriate language where practical.

12. Engineering Data

Engineering values shall include units where applicable.

Examples:

Voltage : 12 V
Current : 5 A
Temperature : 85 °C
Length : 120 mm

13. Figures and Drawings

Figures, diagrams, and engineering drawings shall have meaningful descriptions.

Where applicable, documentation shall identify figure number, figure title, revision, source, and related document.

Engineering drawing requirements are governed by IGB-DOC-004 — Engineering Drawing Standard.

14. Cross-References

Documents shall reference controlled documents using their Document ID and title where practical.

Preferred:

IGB-DOC-001 — Documentation Architecture

Cross-references shall point to the current authoritative document whenever possible.

15. Requirements Language

Requirements shall use precise language.

Where a requirement is mandatory, use:

shall

Where a capability is optional or permitted, use:

may

Where a recommendation is being provided, use:

should

16. Status Terminology

Document status shall use controlled terminology.

Recommended lifecycle states include:

Draft
Review
Approved
Active
Engineering Freeze
Released
Archived

The authoritative lifecycle is defined by IGB-DOC-001 — Documentation Architecture.

17. Revision History

Official documents shall maintain revision history.

Each revision entry should identify:

  • Version
  • Date
  • Description

Revision history shall describe substantive changes.

18. Version Number Placement

Official document versions shall be maintained inside the document.

Version numbers shall not be embedded in the canonical filename.

Correct:

IGB-DOC-002_Documentation_Style_Guide.md

Incorrect:

IGB-DOC-002_Documentation_Style_Guide_v1.0.md

This requirement is inherited from IGB-DOC-001 — Documentation Architecture.

19. File Naming

Filename requirements are governed by:

IGB-DOC-003 — File Naming Convention

This document defines presentation style only and shall not supersede the file naming standard.

20. Git and Version Control

Documentation shall be maintained under Git version control.

Git history is the authoritative historical record for document changes.

Version-control requirements are governed by IGB-DOC-005 — Version Control Policy.

Git workflow requirements are governed by IGB-DOC-006 — Git Workflow Standard.

21. Review Requirements

Documents shall be reviewed according to their document class and lifecycle state.

A review should verify, as applicable:

  • Technical correctness
  • Scope
  • Consistency
  • Traceability
  • Cross-references
  • Status
  • Revision history
  • Formatting
  • Compliance with applicable standards

A document shall not claim an approval state that has not been established by the applicable governance process.

22. Machine Readability

Documentation shall remain suitable for automated processing.

Documents should:

  • Use predictable headings
  • Use stable Document IDs
  • Use structured tables where appropriate
  • Avoid unnecessary formatting complexity
  • Avoid embedding critical information only in images
  • Maintain searchable text

23. Human Readability

Documentation shall remain understandable to qualified engineers without requiring interpretation of undocumented conventions.

Technical abbreviations shall be defined when first introduced unless they are already controlled terminology.

Critical assumptions shall be explicitly documented.

24. Compliance

All official engineering documentation shall comply with this standard where this standard applies.

Non-compliant documents shall be identified and corrected through the applicable documentation or engineering governance process.

This document does not supersede domain-specific engineering standards.

25. Related Documents

Document ID Title Relationship
IGB-DOC-001 Documentation Architecture Parent / Authority
IGB-DOC-003 File Naming Convention Related Standard
IGB-DOC-004 Engineering Drawing Standard Related Standard
IGB-DOC-005 Version Control Policy Related Standard
IGB-DOC-006 Git Workflow Standard Related Standard

Appendix A

Documentation Style Baseline

Controlled Document ID
Controlled Title
Version
Status
Owner
Revision History
Structured Headings
Structured Technical Content
Traceable Cross-References
Git Version Control

Appendix B

Authority Relationship

IGB-DOC-001
Documentation Architecture
        |
        +-- IGB-DOC-002
            Documentation Style Guide

IGB-DOC-002 shall remain subordinate to IGB-DOC-001.

Appendix C

Document Status

Document Status : Approved

Authority : IGB-DOC-001

Owner : IGB Engineering