DTCS Specification Authoring Guide¶
Version: 1.0 Draft
1. Purpose¶
This guide defines the editorial, structural, and normative conventions for all DTCS specifications and companion standards. Its goal is to ensure that every document reads as a coherent standards publication regardless of author.
2. Guiding Principles¶
- Semantics over implementation.
- Contracts over code.
- Deterministic wording.
- Stable terminology.
- Vendor neutrality.
- Backward compatibility whenever practical.
3. Normative Language¶
Use RFC 2119 / RFC 8174 keywords only in ALL CAPS.
Preferred keywords:
- SHALL / SHALL NOT
- SHOULD / SHOULD NOT
- MAY
- MUST / MUST NOT (reserved for absolute requirements when appropriate)
- OPTIONAL
- RECOMMENDED
Avoid lowercase forms for normative requirements.
4. Normative vs. Informative Content¶
Normative:
- Requirements
- Definitions
- Conformance
- Registries
- Required behavior
Informative:
- Notes
- Examples
- Rationale
- Design discussion
- Diagrams
Never mix normative requirements into informative notes.
5. Controlled Vocabulary¶
Canonical terms:
- Transformation Contract
- Canonical Object Model
- Transformation Plan
- Execution Plan
- Semantic Action
- Expression
- Function
- Rule
- Runtime
- Engine
- Planner
- Optimizer
- Compiler
- Validator
- Analyzer
- Diagnostic
Avoid introducing synonyms without defining them.
6. Capitalization¶
Capitalize canonical DTCS concepts exactly as defined.
Examples: - Transformation Plan - Execution Plan - Semantic Action
Use lower case for generic concepts: - transformation - function - compiler (when not referring to the DTCS component)
7. Chapter Template¶
Each chapter SHOULD follow:
- Purpose
- Design Goals
- Core Concepts
- Normative Requirements
- Conformance (if applicable)
- Summary
8. Section Numbering¶
Use decimal numbering:
- Chapter
- x.y section
- x.y.z subsection only when necessary
9. Writing Style¶
- Active voice.
- One concept per paragraph.
- Define before use.
- Avoid ambiguous pronouns.
- Prefer short declarative sentences.
10. Examples¶
Examples SHALL:
- Be marked as informative.
- Demonstrate semantics.
- Avoid implying implementation requirements.
11. Diagrams¶
Prefer ASCII diagrams.
Show conceptual architecture instead of implementation details.
12. Code Blocks¶
Code blocks are illustrative unless explicitly declared normative.
13. Cross References¶
Reference chapters and sections numerically.
Do not duplicate normative definitions across chapters.
14. Identifier Conventions¶
Standard identifiers: - dtcs:*
Vendor identifiers: - vendor: - company:
Identifiers MUST be stable.
15. Registry Templates¶
Every registry entry SHOULD include:
- Identifier
- Purpose
- Parameters
- Type Rules
- Null Behavior
- Lineage
- Compatibility
- Examples
16. Diagnostics¶
Diagnostics should include:
- Identifier
- Severity
- Stage
- Message
- Suggested remediation
17. YAML and JSON¶
YAML is the preferred authoring format.
JSON is the preferred interchange format.
The Object Model is canonical.
18. Diagrams¶
Maintain the canonical architecture:
Transformation Contract → Canonical Object Model → Transformation Plan → Execution Plan → Runtime
19. Conformance Wording¶
Use: - SHALL for mandatory behavior. - SHOULD for recommendations. - MAY for optional behavior.
20. Editorial Rules¶
Avoid: - "simply" - "just" - "obviously" - implementation-specific language in normative sections.
21. Future Evolution¶
Add new concepts without redefining existing semantics.
Preserve identifiers whenever practical.
22. Glossary Maintenance¶
Every new normative term SHOULD be added to the glossary.
23. Appendix Guidance¶
Appendices SHOULD contain: - references - rationale - historical notes - migration guidance
Appendices are informative unless explicitly stated.
24. Quality Checklist¶
Before publication verify:
- Consistent terminology
- Stable identifiers
- Correct RFC keyword usage
- No duplicated definitions
- Clear normative/informative separation
- Cross references validated
- Examples labeled
- Diagrams consistent
- Conformance language present
- Summary included