# Clean Documentation Standard (CDS) **A Global Standard for Specification and Business Documentation** **Author:** Pawel Cyzman **Version:** 1.0 **License:** Open Initiative (Freely available on the official website: [cleandoc.org](http://cleandoc.org)) --- ## Strategic Goals * **Dual Human-AI Readability:** To establish a unified set of documentation characteristics that streamlines interpretation for both human readers and machine systems (including AI agents). * **Universal & Agnostic Applicability:** To design a versatile standard that remains broadly applicable and fully agnostic regarding industry verticals and specific initiative classes. * **Community-Driven Precision:** To foster a dedicated community centered on precision in documentation and specifications, aiming to eliminate redundancy and fluff in an era of mass-generated content. --- ## Standard Principles & AI Guidelines ### 1. Currency and Temporal History * **Principle:** The documentation must explicitly provide precise time tracking for information context. Mandatory elements include clearly visible creation date and last modification date timestamps. > **AI Agent Guidelines (Validation):** > Verify that the document explicitly contains both the creation date and the last modification date timestamps. Flag a validation error if either timestamp is missing. --- ### 2. Context and Intent (Summary & Intent) * **Principle:** The initial section (or metadata area) must contain a concise summary defining the core topic, business objective, and intent behind the document creation. > **AI Agent Guidelines (Validation):** > Confirm the presence of an executive summary/intent section at the beginning of the document. Assess whether a reader can understand the document's topic and target problem in under 30 seconds. --- ### 3. Authorship and Lifecycle (Metadata & Status) * **Principle:** The document must explicitly state its author (person or role), version number, and current lifecycle state (e.g., *Draft / In Review / Approved / Deprecated*). > **AI Agent Guidelines (Validation):** > Check for mandatory fields: Author, Version, and Lifecycle Status. Raise an error or warning if version information is missing or if the status does not match allowed lifecycle states. --- ### 4. Categorization and Content Separation * **Principle:** Substantive elements must be clearly separated by information type (e.g., strictly distinguishing business requirements from business rules, constraints, or assumptions). > **AI Agent Guidelines (Validation):** > Analyze the structure for mixed conceptual categories. Ensure requirements ("what the system should do") are not conflated with business rules ("conditions of business logic"). Highlight instances where rules or assumptions are mislabeled as requirements. --- ### 5. Conceptual Consistency and Glossary * **Principle:** The document must maintain consistent terminology throughout. All acronyms must be expanded upon first use or listed in a dedicated section, and acceptable synonyms explicitly declared. > **AI Agent Guidelines (Validation):** > Detect undefined acronyms, synonym collisions, and term usage inconsistencies. Validate terminology against an internal domain conceptual model grounded in SBVR principles (Semantics of Business Vocabulary and Business Rules)—verifying that business terms, definitions, fact types, characteristics, and rule modalities (necessity, obligation, permission, prohibition, quantification) are unambiguous, non-circular, and structurally consistent. --- ### 6. Standardized Content Architecture * **Principle:** The document must feature a section and heading structure appropriate for its purpose and consistent with the established template for its document family (e.g., Requirements template, Architecture template). > **AI Agent Guidelines (Validation):** > Compare the section layout against the required template for the specific document type. Flag missing mandatory sections and unjustified deviations from the standard layout. --- ### 7. Lean Precision and Conciseness * **Principle:** The document must contain only necessary information, eliminating noise. Descriptions must be unambiguous, concrete, and free from vague qualifiers, balancing space efficiency with high precision. > **AI Agent Guidelines (Validation):** > Flag imprecise, subjective, or ambiguous phrasing (e.g., "fast response time", "high reliability", "where feasible"). Suggest concise alternatives and point out sections containing redundant narrative fluff. --- ### 8. Formal Modeling and Notations * **Principle:** Complex processes, business logic, architecture, and data structures must be visually represented using established formal modeling notations to ensure clarity and eliminate ambiguity. Textual content must maintain 100% alignment with visual models. > **AI Agent Guidelines (Validation):** > Verify whether formal models or diagrams accompany descriptions of complex logic, architecture, or processes. Cross-check textual descriptions against attached diagrams and report any logical discrepancies. Additionally, if complex descriptions lack a visual model, recommend the most suitable notation from established industry standards (e.g., BPMN, UML, ERD, C4 Model, ArchiMate, DFD, State Machines, or API contracts)—selecting the format that best fits the specific domain and complexity of the content. --- ### 9. Contextualization and Traceability (Tagging) * **Principle:** The document must include metadata tags, labels, and links to establish its broader organizational context and enable cross-referencing with related documentation. > **AI Agent Guidelines (Validation):** > Verify the presence of contextual metadata (tags, domain IDs, parent/child linkages). Flag documents that lack traceability to core business entities or domain contexts. Highlight any missing relationships or broken references—such as when the text refers to another document, external specification, or supplementary material that is not properly linked or cited. --- ### 10. Single Point of Responsibility (Business Ownership) * **Principle:** The document must explicitly name a single individual (a human, not a group or system) responsible for the accuracy, validity, and approval of the content. > **AI Agent Guidelines (Validation):** > Verify that the "Business Owner / Person Responsible" field contains a named individual. If the field is missing or lists an impersonal entity (e.g., "IT Team"), flag this as a critical validation error. --- © Clean Documentation Standard (CDS) — Open Initiative Official website: [cleandoc.org](http://cleandoc.org)