About the Archive
Purpose
Codecraft Papers is an archive of technical and scholarly writings. Some are published elsewhere; some are self-published. Documents are categorized according to editorial intent, audience, and level of rigor. These categories are normative rather than descriptive: placement reflects an explicit judgment about the document’s purpose and quality, not merely its topic or length.
Documents classified as Papers are intended to function as citable technical literature. They are written in a formal, declarative style; they define scope and audience explicitly; and they are maintained as versioned works. Papers are expected to include an abstract, substantive argument or analysis, and appropriate citations. Revisions are made sparingly and transparently, with version identifiers indicating material changes.
Other categories may be exploratory, argumentative, or provisional in nature. These documents may evolve more freely and may not meet all of the formal requirements applied to Papers. Category distinctions are preserved deliberately to avoid ambiguity for readers, indexers, and downstream citation or reuse.
Categories
The goal of this taxonomy is to ensure that categories are mutually exclusive and collectively exhaustive, so that each document belongs unambiguously to one category.
- Specifications
-
Documents whose primary purpose is to normatively define behavior such that independent implementations can be evaluated for conformance.
Assignment test
If a reader could reasonably claim that an implementation is compliant or non-compliant with the document, it is a Specification.
Key properties
- Normative authority, explicit or implicit
- Precise definitions, algorithms, or rules
- Versioning is meaningful, but maturity is irrelevant (draft and stable specifications both qualify)
- Papers
-
Documents whose primary purpose is to present an original technical thesis, model, or design, supported by structured reasoning and evidence.
Assignment test
If the document’s main contribution is a technical claim or proposal defended through analysis, and not a teaching guide or conformance target, it is a Paper.
Key properties
- Novelty or synthesis is central
- Conclusions are primarily descriptive
- May introduce frameworks, algorithms, or architectures without asserting normativity
- Analyses
-
Documents whose primary purpose is to examine and reason about an existing artifact, claim, or system in order to understand its properties, implications, or limitations.
Assignment test
If the document’s value lies in explaining or critiquing something that already exists, rather than proposing a new artifact or advocating a position, it is an Analysis.
Key properties
- Object of analysis may be a standard, system, design, or argument
- Conclusions are descriptive or evaluative, not prescriptive
- No attempt to define correctness or to teach from first principles
- Primers
-
Documents whose primary purpose is to teach understanding and build reader competence or mental models.
Assignment test
If the document is optimized for learning and orientation rather than novelty, critique, or prescription, it is a Primer.
Key properties
- Didactic structure
- Explanatory examples and definitions
- Success is measured by reader understanding, not persuasion or adoption
- Comparisons
-
Documents whose primary purpose is to compare two or more mechanisms, systems, or approaches along defined dimensions.
Assignment test
If the document is explicitly structured as A versus B (or A versus B versus C), it is a Comparison.
Key properties
- Multiple subjects analyzed side by side
- Emphasis on tradeoffs, differences, and equivalences
- Distinct from Analyses by plurality of objects
- Guidance
-
Documents whose primary purpose is to enable correct decisions or actions in practice.
Assignment test
If the central reader question is “What should I do?”, the document is Guidance.
Key properties
- Action-oriented recommendations
- Best practices, policies, or codes of conduct
- Content may evolve as conditions change
- Positions
-
Documents whose primary purpose is to advocate a stance about priorities, values, or direction.
Assignment test
If the document’s conclusion is fundamentally “we should”, it is a Position.
Key properties
- Normative and persuasive by design
- Grounded in technical realities but oriented toward judgment or policy
- Distinct from Papers and Analyses by prescriptive intent
Tiebreak Rules
If a document appears to fit multiple categories, apply the following rules in order:
- Normative conformance overrides all; classify as Specification
- Advocacy overrides analysis; classify as Position
- Teaching overrides novelty; classify as Primer
- Action overrides explanation; classify as Guidance
- Multiple objects override single-object analysis; classify as Comparison
If ambiguity remains, classify by the dominant conclusion type presented to the reader.
The following attributes are intentionally not categories and must be expressed as metadata instead:
- Document status (draft, stable, deprecated)
- Maturity or version number
- Narrative or parable style
- Domain or topic area
- Whether an artifact is a standard, draft, algorithm, or framework
This separation preserves category clarity and prevents taxonomy drift.
This editorial policy exists to ensure consistency, clarity, and long-term maintainability of the archive.