IxDF Developer Docs

Appearance

Meta (domain documentation) ​

This document extends the main META document and describes how to write documentation for domain modules.

Purpose ​

Domain docs needed to share knowledge between team members. They are especially useful for onboarding new team members, delegation Module ownership, and making informed decisions.

Structure and Location ​

  1. Directory Structure: Each module MUST have its own directory under /docs/domains/<module-name>.
  2. Main Document: Every module MUST have a README.md file as the main entry point.
  3. Additional Files: For extensive details, create separate .md files within the module's documentation directory and link to them from the README.md.

Content Requirements ​

All documents, as well as code, MUST use the Ubiquitous Language of the domain.

The module documentation SHOULD include the following information (optional sections marked by the pen ✏️ emoji):

  1. ✏️ Table of Contents: Long README.md files should have headings and use [[toc]] (VitePress syntax).
  2. ✏️ Quick references: Provide links to related modules or documentation at the beginning for quick reference.
  3. Module Overview: Explain the module's purpose, role within the application, and the domain concepts it addresses and key functionalities.
  4. ✏️ Terminology and Naming Conventions: Define key terms and concepts relevant to the module.
  5. Key Domain Actions:
    1. Actions: List the main actions or operations that the Module performs and reflect real business processes.
    2. Lifecycle and Process Flows: Use flowcharts or state diagrams to represent lifecycles, processes, or status transitions.
  6. Key Components:
    1. Models: List models, their roles, and relationships between them.
    2. Services and Actions: Describe main services and their responsibilities.
  7. ✏️ Configuration: Describe any configuration settings and environment variables specific to the Module.
  8. ✏️ Architecture:
    1. Design Patterns: Mention key design patterns or architectural styles used and decisions/ADRs behind them.
    2. Architectural Diagrams: Include diagrams using Mermaid.js to illustrate structures, workflows, and interactions.
  9. ✏️ Extensibility and Integration: Provide instructions on how to extend or customize the module (Events and Interfaces).
  10. ✏️ Testing Guidelines: Provide special instructions for testing the module, especially if it differs from standard practices.
  11. Related Documentation: Include links to related documents, modules, or external resources.

Formatting conventions ​

Trophy 🏆 emoji at the beginning and the end of a document is a marker that it satisfies the Golden IxDF standard for documentation.