documentation file templates

• serve as the primary technical specification of the software
• define data carriers, callable interfaces, and algorithms independent of implementation
• describe transformation flows and the composition of algorithms into features

• structures: named data carriers with fields; each field may state a type after a colon or a topology in round brackets
• procedures: function body specifications using a fixed internal structure and restricted logical sentence forms; describe the extensional mapping, admissibility conditions, equivalence, and algebraic properties without algorithmic detail
• signatures: callables mapping input to output
• algorithmic hierarchy: hierarchical overview of algorithms or known concepts used

each procedure entry has the same internal subsections. subsections may be empty but must appear in this order:

• role
• domain
• result
• admissibility
• equivalence
• interaction

syntax:

{{procedure_name}}
  role:
    {{sentence}}
  domain:
    {{sentence}}
  result:
    {{sentence}}
  admissibility:
    {{sentence}}
  equivalence:
    {{sentence}}
  interaction:
    {{sentence}}

the procedure name appears only once as the section header. no duplicate sub-heading is permitted.

sentences inside procedure subsections are restricted to a small set of logical schemas. the listed forms are exemplars, not an exhaustive or exclusive operator set.

• definitional equality

  • x equals f(input_1, ..., input_n)
  • x equals y

• conditional inclusion

  • x is included if and only if p(...)
  • x is included only if p(...)

• relational bounds

  • r(x, y) holds
  • r(x, y) implies r(f(x), f(y))

• cardinality

  • count(x) equals n
  • count(x) <= n
  • count(x) is bounded by n

• uniqueness

  • there exists exactly one x such that p(x)

• algebraic laws

  • f(op(a, b)) equals op(f(a), f(b))

  • r(a, b) implies r(f(a), f(b))

here, r denotes an arbitrary binary relation and op denotes an arbitrary binary operator. no specific ordering or inequality relation is implied or privileged.

prohibited inside procedures:

• narrative or temporal phrasing such as "first", "then", "next", "iterates", "constructs"
• pseudocode, control flow, or data structure choices
• references to specific algorithms or implementation techniques

allowed:

• references to named structures, functions, and fields defined in the same model.it
• references to mathematical functions and relations, provided they are extensional

signature ::= input "->" output
multiple ::= element element ...
alternates ::= element "/" element ...
names ::= type ":" alias ...
optional ::= "[" element ... "]"
repetition ::= element "..."
naming ::= name "::" arguments "->" result
list ::= "(" element ... ")"
map_or_fn ::= "{" key_or_input "->" value_or_output "}"

# {{model name}}
{{general description if not placed in general.it}}

## structures
{{name}}
  {{field}}
  {{field}}: {{type}}
  {{field}}: ({{topology}})
...

## procedures
{{procedure}}
...

## signatures
{{function signatures}}

## algorithmic hierarchy
{{high-level list of algorithms and how they compose the feature}}

• capture why each design decision exists
• record how the decision space evolved
• enable future readers to reconstruct context without redoing the analysis

• represent each consideration as a 3 item structure: question, options, selection.
• an option is any candidate answer paired with its attributes such as pros and cons.
• in cases where there is only one plausible answer, record a single option whose attributes state the reasoning; the selection is that option. this encodes (question, reason, answer).
• in cases with multiple candidates, list all options with their attributes and mark the chosen one as the selection.
• the short form is therefore a single option instance; the long form is multiple option instances.

{{question}}
  {{context}}
  option - selected
    {{attributes}}
  option
    {{attributes}}
  option
    ...

• question: single-line interrogative phrase defining the decision point, written without a trailing question mark
• context: minimal constraints, facts, or background needed to interpret the options
• option - selected: the adopted solution
• option: a considered but unselected alternative
• attributes: any combination of description, evaluation criteria, advantages, disadvantages, constraints, or other facts relevant to comparing this option
• if an option introduces substantial branching, create a separate entry for that branch

• record exploratory, provisional, or uncertain material
• serve as a staging area for content that may later migrate into structured files
• hold volatile or speculative reasoning without committing to final form

• unconstrained free-form text
• any mixture of prose, lists, sketches, or pseudo-code
• material may be incomplete, conflicting, or intentionally experimental

{{topic}}
  {{idea or fragment}}
    {{sub-detail}}
{{topic}}
  {{note text}}

• state the minimal high-level specification of the system
• define stable conceptual foundations and system-wide intent
• record global semantics and cross-cutting properties that anchor all other files

• concise overarching principles
• invariant domain concepts
• system-wide assumptions and semantics
• definitions required for consistent interpretation of all subordinate documents