Skip to main content

ADR-004: English as the Primary Documentation Language

Context​

The project involves collaboration with advanced AI agents and potentially international stakeholders or future team expansion. Mixing languages (Italian/English) creates friction in indexing, searchability, and AI comprehension.

Decision​

Primary Language: English​

All repository content MUST use English as the primary language for:

  • Architecture Decision Records (ADRs)
  • Code (comments, variable names, function names)
  • Technical specifications and API documentation
  • Public-facing documentation in the Docusaurus portal

Exception: Internal Collaboration Documents​

The following document types MAY use Italian to facilitate team efficiency:

  • Internal handover documents (e.g., HANDOVER-*.md in 00-Meta/01-Guidelines/)
  • Onboarding guides for Italian-speaking team members
  • Team discussion notes in 00-Meta/05-Debates/ (when marked as internal)

Bilingual Guidelines​

If an internal document in Italian exceeds 500 words:

  • SHOULD provide an English summary at the top (2-3 paragraphs)
  • OR include inline English annotations for key technical terms and decisions

Consequences​

  • Positive: Unified knowledge base, improved AI performance (LLMs excel in English), and better interoperability with global standards.
  • Negative: Potential initial friction for non-native team members during content creation.