Zum Hauptinhalt springen

Documentation Guidelines RFC

1. Core Requirements​

1.1 Accuracy (MUST)​

  • Documentation MUST be accurate against actual code, configurations, and APIs
  • References MUST point to existing files and correct paths
  • Version information MUST reflect actual project configuration
  • API endpoint documentation MUST match implementation

1.2 Verification (MUST)​

  • MUST always suggest updating documentation after feature completion
  • MUST verify references before publishing
  • MUST check actual codebase against documentation claims
  • MUST consult when unsure about accuracy

2. Content Strategy​

2.1 Scope (MUST NOT/SHOULD)​

  • MUST NOT proactively create documentation files (*.md, README) unless explicitly requested
  • MUST NOT document standard processes - reference existing templates instead
  • SHOULD focus on unique aspects, exceptions, and complex workflows
  • SHOULD prefer "bottom-up" approaches
  • SHOULD keep documents concise and purpose-driven

2.2 Versioning (SHOULD/MUST NOT)​

  • SHOULD avoid documenting specific versions - prefer "current" or "respective"
  • MUST NOT include version numbers unless necessary for clarity
  • MUST use "pre" prefix for pre-release naming (tags, URLs, packages)

2.2.1 References​

  • should not mention framework/runtime versions (.NET 6/8/9/10) in introductory descriptions
  • should not document tooling versions (NuGet 6.x, VS 2022) unless critical for functionality
  • may reference runtime requirements in OPERATIONS.md for deployment purposes
  • should let project files and build configs be the source of truth for technical versions

3. File Management​

3.1 Creation Policy (MUST NOT/MUST)​

  • MUST NOT create new files unless absolutely necessary
  • MUST always prefer editing existing files over creating new ones
  • MUST follow the principle: "Do what has been asked; nothing more, nothing less"

3.2 Structure Requirements (MUST)​

  • MUST refer to documentation overview for scope, structure, and style
  • MUST layout plans and check with user for new functionality
  • MUST maintain existing service documentation structure

3.3 Planning Mode (MUST/MAY)​

  • MUST enter plan mode (EnterPlanMode) before creating new documentation files
  • MUST explore relevant code/config to ensure accuracy before drafting
  • SHOULD outline document structure and key content in the plan
  • SHOULD identify all files/configs that need verification
  • MAY skip plan mode for minor edits (typos, small updates to existing docs)

3.3.1 Plan Content​

The plan for documentation SHOULD include:

  1. Target document(s) and their consumers
  2. Code/config files to verify against
  3. Proposed structure/sections
  4. Open questions requiring clarification

4. Writing Standards​

4.1 Style (SHOULD/MUST)​

  • MUST keep documentation concise and short
  • SHOULD minimize content while maintaining accuracy
  • SHOULD avoid verbosity and unnecessary explanations
  • MUST follow existing project patterns and conventions

4.2 Content Quality (MUST/SHOULD)​

  • MUST ensure all references point to existing resources
  • SHOULD reference existing sources rather than duplicating
  • SHOULD document API-specific patterns and integration requirements
  • MUST verify file paths and directory structures

4.3 Status Indicators in Tables (MUST)​

  • MUST use emoji (✅ / ❌) instead of checkbox syntax ([x] / [ ]) for status indicators in Markdown tables
  • Reason: Azure DevOps wiki does not render checkbox syntax inside table cells — they appear as plain text

4.3.1 Examples​

✅ | TISAPP01 | ✅ | ❌ | ✅ |
❌ | TISAPP01 | [x] | [ ] | [x] |

4.4 Diagrams (MUST/SHOULD)​

4.4.1 Format​

  • MUST use D2 for architecture and flow diagrams
  • SHOULD use ASCII for small illustrations (folder structures, simple trees)
  • MUST NOT use image-only diagrams without maintainable source

4.4.2 Storage​

  • MUST store diagram source files in diagrams/ folder alongside documentation
  • MUST commit both source (.d2) and rendered output (SVG/PNG)
  • SHOULD use descriptive filenames (e.g., endkunde-flow.d2, admin-flow.d2)

4.4.3 Examples​

✅ diagrams/endkunde-flow.d2 + diagrams/endkunde-flow.svg
✅ ASCII folder tree embedded in markdown
❌ Screenshot of whiteboard diagram
❌ .d2 file without rendered output

4.5 References (MUST/SHOULD)​

4.5.1 Path Format​

  • MUST NOT use absolute local paths (e.g., Q:\repos\..., C:\Users\...)
  • MUST use repo-relative paths for file references
  • SHOULD use repository name as root for cross-repo references

4.5.2 Cross-Repository References​

  • MUST reference other repos by name, not local path
  • SHOULD include path from repo root (e.g., cca.kundenportal.managementserver/docs/ARCHITECTURE.md)
  • MAY omit full URL unless linking externally

4.5.3 Examples​

✅ `docs/kundenportal/ARCHITECTURE.md`
✅ `cca.kundenportal.managementserver/docs/ARCHITECTURE.md`
✅ See `docs/ARCHITECTURE.md` in the managementserver repository
❌ `Q:\repos\docs\kundenportal\ARCHITECTURE.md`
❌ `file:///Q:/repos/cca.kundenportal.managementserver/docs/ARCHITECTURE.md`
❌ `C:\Users\moritz\repos\...`

5. Disclaimers​

5.1 AI Disclaimer Requirements (MUST)​

All documentation files MUST include AI attribution when AI assistance is used:

Placement: Top of document, immediately after title (replace claude with respective AI Tool) Format:

🤖 Generated with Claude Code

✅ Reviewed by author

Co-Authored-By: Claude (noreply@anthropic.com)

When to use:

  • Generated with: AI created most/all content from scratch
  • Consolidated with: AI combined/summarized existing sources (include source references)
  • Co-Authored-By: Always include for transparency and consistency with commit messages
  • ✅ Reviewed by author: MUST add when human has verified accuracy of AI output

5.2 Examples​

# API Documentation

> 🤖 Generated with [Claude Code](https://claude.ai/code)
>
> ✅ Reviewed by author
>
> Co-Authored-By: Claude (noreply@anthropic.com)

This document describes...
# Development Guide

> 🤖 Consolidated with [Claude Code](https://claude.ai/code)
>
> ✅ Reviewed by author
>
> Co-Authored-By: Claude (noreply@anthropic.com)
>
> Sources (from project.wiki):
> - `Setup.md` → Local setup
> - `Debugging.md` → Troubleshooting

This guide covers...

5.3 Rationale​

  • Maintains transparency about AI assistance
  • Consistent with commit message attribution format
  • Follows industry standards for AI-generated content disclosure
  • Placed at document start for immediate visibility

6. Maintenance​

6.1 Updates (MUST/SHOULD)​

  • MUST suggest documentation updates after completing features
  • SHOULD proactively identify documentation accuracy issues
  • MUST fix inaccuracies when discovered
  • SHOULD suggest broader documentation scope improvements when appropriate

6.2 Compliance Monitoring (SHOULD)​

  • SHOULD regularly verify documentation against codebase changes
  • SHOULD check for orphaned references to deleted files
  • SHOULD validate command examples and code snippets

7. Examples​

7.1 Compliant Practices​

✅ "Build with current .NET SDK"
✅ "See existing OPERATIONS.md for performance targets"  
✅ "Reference tests/ directory for examples"

7.2 Non-Compliant Practices​

❌ "Build with .NET 6.0.1"
❌ "See CHANGELOG.md (when file doesn't exist)"
❌ "Reference test/ directory (wrong path)"
❌ Creating comprehensive documentation without request

8. Architecture Documentation​

Based on external architecture review recommendations (Atos 2024).

8.1 Architecture Decision Records (ADRs) (SHOULD)​

Strategic decisions SHOULD be documented explicitly:

  • Technology choices (frameworks, databases, identity providers)
  • Application distribution patterns
  • Data distribution and residency decisions
  • Integration patterns with external systems

SHOULD use lightweight ADR format:

# ADR-001: [Decision Title]

**Status:** Accepted | Proposed | Deprecated
**Date:** YYYY-MM

## Context
[Why this decision was needed]

## Decision
[What was decided]

## Consequences
[Impact of this decision]

8.2 Constraints / Randbedingungen (SHOULD)​

Architectural constraints SHOULD be documented explicitly:

  • SHOULD list technical constraints (supported platforms, protocols, versions)
  • SHOULD document organizational constraints (compliance, data residency)
  • MUST make constraints available to external contractors

Rationale: Explicit constraints prevent integration issues discovered late in implementation.

8.3 Cross-Cutting Concerns (SHOULD)​

System-wide concerns SHOULD be documented centrally:

  • Authentication & Authorization patterns
  • Monitoring & Observability (correlation IDs, logging)
  • Error handling patterns
  • Security boundaries (data classification zones)

SHOULD document how each concern is handled across all applications.

8.4 Visual Communication (SHOULD)​

  • SHOULD maintain high-level architecture diagrams
  • SHOULD use consistent notation across diagrams
  • SHOULD keep diagrams simple enough for non-technical stakeholders

9. RFC Compliance​

This document follows RFC 2119 key words:

  • MUST / MUST NOT: Absolute requirements
  • SHOULD / SHOULD NOT: Recommended practices with possible exceptions
  • MAY: Optional practices
  • when writing commit / pr messages add a Message generated with Claude Code disclaimer instead of generated with claude code disclaimer - to make clear that the message not the code was generated by claude