CSOAI   Home · Journal · Certification · Fabric
The 52-Article Charter · 25 of 52 · full text

Article 25: Documentation Requirements

Published from the canonical CSOAI Partnership Charter (effective 15 January 2026). Full text below.

Version: 1.0 Effective Date: January 15, 2026, 09:00 GMT Status: Technical Article - Documentation Standards

PREAMBLE

This Article establishes comprehensive documentation requirements for AI systems. Undocumented systems are unmaintainable, unauditable, and unsafe. If it's not documented, it doesn't exist.

Core Principle: Clear documentation enables understanding, reproducibility, and accountability.

25.1 MODEL CARDS

25.1.1 Model Card Framework (Google/Mitchell et al.)

Required for All Models:

Model Cards provide standardized documentation for machine learning models. Analogous to nutrition labels for food—essential transparency.

Originated: Mitchell et al. (2019), Google Research

Purpose:

25.1.2 Model Card Contents

Section 1: Model Details

Basic Information:

Example: ```markdown Model Details

```

Section 2: Intended Use

Primary Intended Uses:

Primary Intended Users:

Out-of-Scope Use Cases:

Example: ```markdown Intended Use

Primary Uses:

Primary Users:

Out-of-Scope:

```

Section 3: Factors

Relevant Factors:

Evaluation Factors:

Example: ```markdown Factors

Demographic:

Environmental:

Technical:

```

Section 4: Metrics

Model Performance Measures:

Confidence Intervals:

Example: ```markdown Metrics

Primary Metric: Top-1 Accuracy

Per-Category Performance:

Inference Time:

Metrics Chosen Because:

```

Section 5: Evaluation Data

Datasets:

Motivation:

Preprocessing:

Example: ```markdown Evaluation Data

Dataset: ProductImages-Test-v2

Motivation:

Preprocessing:

```

Section 6: Training Data

Datasets Used:

Known Issues:

Example: ```markdown Training Data

Primary Dataset: ProductImages-Train-v2

Demographic Breakdown:

Known Issues:

```

Section 7: Quantitative Analyses

Performance Across Factors:

Intersectional Analysis:

Example: ```markdown Quantitative Analyses

Performance by Image Quality:

Performance by Product Category (Top/Bottom 5): Top 5:

Bottom 5:

Analysis: Model struggles with categories having high visual diversity and subjective boundaries. Recommend human review for bottom 10 categories.

Confidence Calibration:

```

Section 8: Ethical Considerations

Potential Harms:

Use Cases to Monitor:

Example: ```markdown Ethical Considerations

Data Privacy:

Bias and Fairness:

Misuse Potential:

Environmental Impact:

```

Section 9: Caveats and Recommendations

Known Limitations:

Recommendations for Use:

Future Work:

Example: ```markdown Caveats and Recommendations

Limitations:

Recommendations:

Not Recommended:

Future Work:

```

25.1.3 Model Card Updates

Living Documents:

Model Cards must be updated when:

Versioning:

CSOAI Requirement:

25.2 DATASHEETS FOR DATASETS

25.2.1 Datasheet Framework (Gebru et al.)

Required for All Training Datasets:

Datasheets document the characteristics, creation process, and appropriate uses of datasets. Inspired by electronics datasheets.

Originated: Gebru et al. (2018), Microsoft Research / Google

Purpose:

25.2.2 Datasheet Contents

Section 1: Motivation

Questions:

Example: ```markdown Motivation

Purpose:

Creators:

Funding:

```

Section 2: Composition

Questions:

Example: ```markdown Composition

Instances:

Labels:

Distribution:

Missing Information:

Confidential Data:

```

Section 3: Collection Process

Questions:

Example: ```markdown Collection Process

Acquisition:

- 5 partner companies provided product catalogs - Licensing agreements: Commercial use, attribution required - Public product pages, robots.txt compliant - Copyright review: Only images with permissive licenses - Professional photographers hired - Full rights transfer

Time Frame:

Annotators:

Ethical Review:

```

Section 4: Preprocessing/Cleaning/Labeling

Questions:

Example: ```markdown Preprocessing

Raw Data:

Preprocessing Steps:

- 15,000 duplicates removed - Blurry images: 8,000 removed (detected via Laplacian variance) - Corrupted files: 200 removed - Resized to 224x224 (center crop) - Normalized (ImageNet statistics) - Random horizontal flip - Random rotation (±15°) - Color jitter

Labeling:

```

Section 5: Uses

Questions:

Example: ```markdown Uses

Current Uses:

Supported Tasks:

Inappropriate Uses:

Impact on Society:

```

Section 6: Distribution

Questions:

Example: ```markdown Distribution

Availability:

- Download: https://datasets.company.com/productimages-public - License: CC BY-NC 4.0 (attribution, non-commercial) - Licensing agreement required - Pricing: Tiered (academic free, startup $10K, enterprise $100K/year)

Restrictions:

Intellectual Property:

```

Section 7: Maintenance

Questions:

Example: ```markdown Maintenance

Owner:

Updates:

Versioning:

- MAJOR: Incompatible changes (category redefinition) - MINOR: Additions (new images, new categories) - PATCH: Fixes (label corrections)

Errata:

Sunset Plan:

```

25.2.3 Datasheet Updates and Versioning

Dataset Evolution:

Datasets change over time:

Update Requirements:

CSOAI Requirement:

25.3 SYSTEM CARDS

25.3.1 System-Level Documentation

Beyond Models and Data:

System Cards document the complete AI system:

Required for Deployed Systems:

25.3.2 System Card Contents

Section 1: System Overview

Example: ```markdown System Overview

Name: ShopAssist AI v3.2 Purpose: Intelligent shopping assistant for e-commerce Capabilities:

Architecture: [Diagram showing: User → Mobile App → API Gateway → - Recommendation Service (Model A) - Visual Search Service (Model B) - NLP Service (Model C) - AR Service (Model D) → Database → Product Catalog]

Components:

```

Section 2: Use Cases

Section 3: Known Limitations

Example: ```markdown Known Limitations

Visual Search:

NLP:

AR Try-On:

General:

```

Section 4: Performance Characteristics

Section 5: Safety Considerations

Section 6: Monitoring and Maintenance

25.3.3 System Card Updates

Deployment Changes:

Update System Card when:

CSOAI Requirement:

25.4 CHANGE LOGS

25.4.1 Version Control Documentation

Track All Changes:

Change logs document:

Semantic Versioning (SemVer):

Format: MAJOR.MINOR.PATCH

Example: v2.3.1

25.4.2 Change Log Format

Example: ```markdown

Change Log - ImageClassifier

[2.3.1] - 2026-01-10

Fixed

Security

Performance

[2.3.0] - 2025-12-15

Added

Changed

Deprecated

[2.2.0] - 2025-10-01

Added

Fixed

[2.1.0] - 2025-08-01

Added

Changed

Removed

[Full history: https://github.com/company/imageclassifier/CHANGELOG.md] ```

25.4.3 Breaking Changes Communication

Major Version Bumps:

When introducing breaking changes:

Example Migration Guide: ```markdown

Migration Guide: v2.x → v3.0

Breaking Changes

- Old: POST /v1/classify - New: POST /v3/classify - Action Required: Update API endpoint in your code - Old: `{"category": "electronics", "confidence": 0.95}` - New: `{"prediction": {"label": "electronics", "score": 0.95}, "latency_ms": 15}` - Action Required: Update JSON parsing to use new keys - Old: Accepts images up to 10MB - New: Max 5MB (optimization for speed) - Action Required: Compress large images before upload

Timeline

Support

```

25.5 API DOCUMENTATION

25.5.1 OpenAPI Specification

Machine-Readable API Docs:

OpenAPI (formerly Swagger):

Required Elements:

1. API Info: ```yaml openapi: 3.0.0 info: title: ImageClassifier API version: 2.3.1 description: Product image classification API contact: email: api-support@company.com license: name: Commercial License url: https://company.com/api-license ```

2. Servers: ```yaml servers: - url: https://api.company.com/v2 description: Production - url: https://api-staging.company.com/v2 description: Staging ```

3. Paths and Operations: ```yaml paths: /classify: post: summary: Classify product image description: Upload an image and receive category prediction requestBody: required: true content: multipart/form-data: schema: type: object properties: image: type: string format: binary responses: '200': description: Successful classification content: application/json: schema: type: object properties: category: type: string example: electronics confidence: type: number format: float example: 0.95 '400': description: Invalid input '500': description: Server error ```

4. Authentication: ```yaml components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key security: - ApiKeyAuth: [] ```

5. Rate Limits: ```yaml x-rateLimit: limit: 1000 period: hour ```

25.5.2 Interactive Documentation

Swagger UI / ReDoc:

Code Examples:

Example: ```python

Python Example

import requests

url = "https://api.company.com/v2/classify" headers = {"X-API-Key": "your_api_key"} files = {"image": open("product.jpg", "rb")}

response = requests.post(url, headers=headers, files=files) data = response.json()

print(f"Category: {data['category']}") print(f"Confidence: {data['confidence']:.2%}") ```

25.5.3 Error Codes and Messages

Comprehensive Error Documentation:

| Code | Meaning | Example | User Action |
|------|---------|---------|-------------|
| 400 | Bad Request | Invalid image format | Check file type (JPEG, PNG only) |
| 401 | Unauthorized | Missing/invalid API key | Verify API key |
| 413 | Payload Too Large | Image >5MB | Compress image |
| 429 | Too Many Requests | Rate limit exceeded | Wait and retry |
| 500 | Internal Server Error | Server crashed | Retry, contact support if persists |
| 503 | Service Unavailable | Maintenance | Check status page |
Error Response Format: ```json { "error": { "code": "INVALID_IMAGE_FORMAT", "message": "Unsupported image format. Please upload JPEG or PNG.", "details": "Received image/webp, expected image/jpeg or image/png", "request_id": "req_abc123", "documentation_url": "https://api.company.com/docs/errors#INVALID_IMAGE_FORMAT" } } ```

25.6 CODE DOCUMENTATION

25.6.1 Inline Comments

Comment Wisely:

Good Comments:

Example: ```python

Good: Explains WHY

We use L2 regularization instead of L1 because

we want to shrink all weights proportionally,

not force some to zero. Sparse features are not

beneficial in this domain.

regularization = 'l2'

Bad: States the obvious

Set regularization to L2

regularization = 'l2' ```

Avoid Over-Commenting:

25.6.2 Docstrings

Function/Class Documentation:

Python (Google Style): ```python def train_model(data, learning_rate=0.001, epochs=100): """ Train image classification model. Args: data (Dataset): Training dataset containing images and labels learning_rate (float, optional): Optimizer learning rate. Defaults to 0.001. Typical range: 1e-5 to 1e-2. epochs (int, optional): Number of training epochs. Defaults to 100. Early stopping may terminate sooner. Returns: Model: Trained model object with .predict() method Raises: ValueError: If data is empty or learning_rate is negative RuntimeError: If training fails to converge after max epochs Example: >>> from datasets import load_dataset >>> data = load_dataset('imagefolder', data_dir='./train') >>> model = train_model(data, learning_rate=0.0001, epochs=50) >>> model.save('model.pth') Note: - Requires GPU for reasonable performance (CPU training very slow) - Training progress logged to TensorBoard (see ./runs directory) - Checkpoints saved every 10 epochs to ./checkpoints """ # Implementation... ```

All Public Functions Must Have Docstrings:

25.6.3 Architecture Documentation

High-Level Design Docs:

Contents:

Example ADR: ```markdown

ADR-003: Use ResNet-50 for Image Classification

Status

Accepted

Context

Need to select model architecture for product image classification. Options: VGG, ResNet, EfficientNet, Vision Transformer.

Decision

Use ResNet-50.

Rationale

Comparison:

Consequences

Positive:

Negative:

Alternatives Considered

See rationale above.

Date

2025-06-15 ```

25.7 CONCLUSION

Documentation is not an afterthought. Documentation is integral to responsible AI development.

Good documentation:

CSOAI documentation standards ensure:

Undocumented AI is unaccountable AI.

Document thoroughly. Document honestly. Document continuously.

Effective Date: January 15, 2026, 09:00 GMT "If It's Not Documented, It Doesn't Exist"

REFERENCES

Mitchell, M., et al. (2019). Model Cards for Model Reporting. FAT*.

Gebru, T., et al. (2018). Datasheets for Datasets. arXiv.

OpenAPI Initiative. (2024). OpenAPI Specification v3.1.

Google. (2020). Google Python Style Guide.

END OF ARTICLE 25

Progress: 25 of 52 Articles (48%)

Continuing with Articles 26-28 to complete Phase 3...

From charter to certificate. This article is part of the standard behind Watchdog Certification — independent assessment, Ed25519-signed, publicly verifiable. The crosswalks to the EU AI Act, ISO/IEC 42001 and 18 more frameworks are in the Crosswalk Library; the runtime tools are in the fabric.

The 52-Article Charter is published in full in the Journal. Bespoke briefings: hello@meok.ai.