Instruction file imported from paonath/PH.DapperUtils.UnitOfWork (.github/instructions/documentation.instructions.md). Copyright stays with the author.

Documentation Generation Instructions

Purpose: Generate self-contained, AI-parseable documentation with unified technical and functional chapters.

Table of Contents

• Documentation Structure
• File Template
• Content Guidelines
• Versioning & Maintenance
• AI Assistant Directives

Documentation Structure

Single-File, Two-Chapter Approach

Each documentation file must be self-contained and AI-parseable:

• ✅ One markdown file per topic/feature/module
• ✅ Two mandatory chapters: Technical + Functional
• ✅ Complete metadata header for version tracking
• ✅ No external dependencies between files
• ✅ Human-readable with clear visual separation

Rationale: A unified file ensures:

• AI can process entire context in one pass
• No broken links between technical/functional sections
• Easier maintenance and version control
• Single source of truth per topic

Chapter 1: Technical Documentation

Target: Developers, AI code analysis, system architects
Heading prefix: All H2 must start with Technical:

Required content:

• Architecture overview (include mermaid diagrams)
• Code structure: DAL, BLL, UI layers
• API endpoints: METHOD /path → {response_format}
• Design patterns and key algorithms
• Code snippets (< 20 lines, essential logic only)
• Dependencies table (last subsection)

Example H2 headings:

• ## Technical: Architecture Overview
• ## Technical: API Endpoints
• ## Technical: Dependencies

Chapter 2: Functional Documentation

Target: Project managers, end-users, QA, maintainers
Heading prefix: All H2 must start with Functional:

Required content:

• Feature descriptions (what it does)
• User workflows (step-by-step guides)
• Configuration options
• Usage scenarios with examples
• Screenshots/diagrams for UI (when applicable)
• Troubleshooting common issues

Example H2 headings:

• ## Functional: User Authentication Flow
• ## Functional: Configuration Options
• ## Functional: Common Issues

File Template

Metadata Header (YAML front matter)

---
title: [Feature/Module Name]
summary: [1-4 sentence description]
commit: [git hash]
date: [YYYY-MM-DD]
branch: [branch name]
review_date: [YYYY-MM-DD]
---

Complete File Structure

See examples/documentation-template.md for the full file template.

Content Guidelines

Writing Style

• Clarity first: Define technical terms on first use
• Conciseness: One main idea per paragraph
• Consistency: Use same terminology throughout both chapters
• Scannable: Heavy use of bullet points, tables, code blocks

Code References

✅ Do:

• Link to files with line numbers: src/Auth/JwtService.cs#L45-60
• Reference specific entities: IAuthService, LoginController.Authenticate()
• Show complete request/response examples
• Use inline code for class/method names: UserManager

❌ Don't:

• Paste entire class files (use snippets < 20 lines)
• Include auto-generated code
• Repeat same code in both Technical and Functional sections
• Use ambiguous references like "the service" or "that method"

Visual Aids

• mermaid.js diagrams for Technical section (architecture, sequence, class)
• Screenshots for Functional section (UI workflows)
• ASCII diagrams for simple flows in both sections
• Tables for comparing options, listing endpoints, dependencies

Language Detection

• Auto-detect: Match the language of source code comments
• Fallback: English (append .en.md to filename)
• Multilingual projects: Create separate files
  • authentication.it.md (Italian)
  • authentication.en.md (English)
  • Link between them in metadata: translations: [en, it]

Versioning & Maintenance

Critical Rules

⚠️ NEVER increment project version for documentation-only changes
⚠️ Requires explicit maintainer approval for ANY version bump

Metadata Requirements

Every file must include in YAML header:

• commit: Git hash when doc was created/updated
• date: Last modification date (YYYY-MM-DD)
• branch: Source branch name
• review_date: Next scheduled review (quarterly for technical, annually for functional)

Change Tracking

• Log in CHANGELOG.md under ## [Documentation] section:

  ## [Documentation] - 2025-01-16
  ### Added
  - Authentication system documentation (commit: a1b2c3d)
  ### Updated
  - API endpoints for user management (commit: e4f5g6h)

Git Commit Format

docs: [area] brief description

- Detail 1
- Detail 2

Commit: a1b2c3d | Review: 2025-04-16

Example:

docs: add authentication system documentation

- Include JWT flow diagram
- Document OAuth2 integration
- Add troubleshooting section

Commit: a1b2c3d | Review: 2025-04-16

AI Assistant Directives

Automated Generation Steps

When generating documentation from code:

1. Extract metadata:

   • Run git log -1 --format="%H|%ai|%D" to get commit/date/branch
   • Parse project file for version and dependencies

2. Analyze codebase:

   • Identify layers (DAL/BLL/UI)
   • Extract API endpoints from controllers
   • Map dependencies from package files

3. Generate Technical chapter FIRST:

   • Create architecture diagram (mermaid)
   • Document code structure with references
   • List all dependencies with versions
   • Include essential code snippets

4. Derive Functional chapter from Technical:

   • Translate technical flows into user steps
   • Create usage examples from API endpoints
   • Extract configuration from code comments
   • Identify common error scenarios

5. Validate output:

   • Check markdown syntax (use linter)
   • Verify all internal TOC links work
   • Ensure both chapters are present
   • Confirm metadata is complete

6. File naming:

   • Use kebab-case: user-authentication.md
   • Match main code entity: OrderService.cs → order-service.md
   • Add language suffix if needed: order-service.it.md

Quality Checklist

Before finalizing documentation, verify:

• YAML metadata is complete (title, summary, commit, date, branch, review_date)
• Summary is 1-4 sentences maximum
• TOC has separate Technical and Functional sections
• All H2 headings have correct prefix (Technical: or Functional:)
• Technical chapter includes Dependencies table
• Code references use valid file paths with line numbers
• Mermaid diagrams render correctly
• No section exceeds 500 lines (split if necessary)
• Markdown passes validation (no broken links)
• No version numbers changed without approval
• Language matches code comments or defaults to English

File Size Management

• Target: 200-500 lines per file
• If > 500 lines: Split into multiple files by logical topic
  • user-authentication.md (overview + flows)
  • user-authentication-api.md (detailed API reference)
  • Link between files in "Related Documentation" section