koodideks

Koodideks is a concept and proposed standard in software documentation that encodes code, metadata, and explanatory text into a single portable file format. The name derives from Estonian kood meaning 'code' and the suffix -deks, implying 'for codes' or 'to be used with codes'. The idea is to improve the reuse, discoverability, and localization of code examples across programming languages and learning contexts.

A koodideks file typically comprises a metadata header, a sequence of code blocks, and an annotation section. The metadata may include title, author, date, license, programming language, and required dependencies. Code blocks are tagged with a language indicator and may specify execution environment details. Annotations provide narrative explanations, tests or examples, and cross-references to related materials. The format emphasizes portability: code blocks should be extractable and runnable in different environments, while annotations remain readable in plain text.

Benefits of the approach include better maintainability of tutorials and open-source documentation, easier translation, and support for literate programming workflows. It also aligns with the growing demand for doc-as-code, reproducible examples, and tooling for automated verification and testing of examples.

Status: koodideks is discussed as a conceptual framework rather than a formal, widely adopted standard. Several experiments and tools have been proposed to realize its principles, but there is no universal specification accepted in major ecosystems.

See also: literate programming, documentation as code, and doc formats used in notebooks.