# documentation file templates
templates for structuring documentation files. the files can be split as required.

the format can be anything that supports outlines, including [plaintext formats](/computer/designs/plaintext-formats.html).

text surrounded by {{}} is non-literal and the result replaces the text including the braces.

## goals
* domain-specific specification sheets
* compact field manuals defining essential dimensions, categories, and procedures.
* building compact documents for humans and chatbots to acquire system understanding quickly

## file: `model.it`
### purpose
* 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

### contents
* 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

### procedures: internal structure
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.

### procedures: sentence forms
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

### function signature syntax
```
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 "}"
```

### template
```
# {{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}}
```

## file: `considerations.it`
### purpose
* capture why each design decision exists
* record how the decision space evolved
* enable future readers to reconstruct context without redoing the analysis

### contents
* 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.

### entry format
```
{{question}}
  {{context}}
  option - selected
    {{attributes}}
  option
    {{attributes}}
  option
    ...
```

### element definitions
* 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

## file: `notes.it`
### purpose
* 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

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

### template
```
{{topic}}
  {{idea or fragment}}
    {{sub-detail}}
{{topic}}
  {{note text}}
```

## file: `general.it`
### purpose
* 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

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