07 - Documentazione Professionale con Copilot

Documentazione Professionale con Copilot

La documentazione è spesso l'aspetto più trascurato dello sviluppo software, eppure è fondamentale per la manutenibilità e l'onboarding di nuovi sviluppatori. Una documentazione ben scritta può risparmiare ore di debugging e confusione. Con GitHub Copilot, scrivere documentazione professionale diventa veloce e sistematico.

In questo articolo esploreremo come usare Copilot per creare README professionali, documentazione API con OpenAPI, Architecture Decision Records, JSDoc completi e changelog ben strutturati.

Tipi di Documentazione

Un progetto professionale richiede diversi tipi di documentazione, ognuno con uno scopo specifico.

README Professionale

Il README è la prima cosa che un visitatore vede. Deve comunicare rapidamente cosa fa il progetto, come usarlo e come contribuire.

Prompt per README Completo

Create a professional README.md for my project:

PROJECT INFO:
- Name: TaskFlow
- Type: SaaS task management for freelancers
- Stack: Node.js 20, Express 5, TypeScript 5.3, PostgreSQL 16, Angular 17
- Status: Beta (production-ready)
- License: MIT

FEATURES:
1. Project and task management with drag-and-drop
2. Time tracking with automatic reminders
3. Invoice generation from tracked time
4. Team collaboration (up to 5 users)
5. Integrations: Slack, Google Calendar, Stripe

SECTIONS TO INCLUDE:
1. Project title with logo placeholder and badges
2. One-paragraph description (compelling, benefit-focused)
3. Screenshots/demo section
4. Key features list with icons
5. Tech stack with version badges
6. Prerequisites
7. Installation (step-by-step, copy-pasteable)
8. Configuration (environment variables table)
9. Usage examples with code
10. API documentation link
11. Testing instructions
12. Deployment guide
13. Contributing guidelines
14. Roadmap (future features)
15. License
16. Contact/support info

STYLE:
- Use emojis sparingly for visual hierarchy
- Include copy-paste ready commands
- Add collapsible sections for detailed content
- Include badges from shields.io

Template README Completo

# TaskFlow

<p align="center">
  <img src="docs/images/logo.png" alt="TaskFlow Logo" width="200">
</p>

<p align="center">
  <strong>The smart task management platform for freelancers</strong>
</p>

<p align="center">
  <a href="#features">Features</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#documentation">Documentation</a> •
  <a href="#contributing">Contributing</a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/version-1.0.0-blue" alt="Version">
  <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
  <img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build">
  <img src="https://img.shields.io/badge/coverage-87%25-yellow" alt="Coverage">
  <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node">
</p>

---

## Overview

TaskFlow helps freelancers and small teams manage projects, track time,
and generate invoices - all in one place. Stop juggling multiple tools
and focus on what matters: delivering great work.

<p align="center">
  <img src="docs/images/screenshot-dashboard.png" alt="Dashboard" width="80%">
</p>

## Features

| Feature | Description |
|---------|-------------|
| 📋 **Task Management** | Kanban boards, lists, and calendar views |
| ⏱️ **Time Tracking** | One-click timer with automatic reminders |
| 💰 **Invoicing** | Generate professional invoices from tracked time |
| 👥 **Team Collaboration** | Real-time sync for teams up to 5 members |
| 🔗 **Integrations** | Slack, Google Calendar, Stripe |
| 📊 **Analytics** | Weekly reports and productivity insights |

## Tech Stack

| Layer | Technology |
|-------|------------|
| **Backend** | Node.js 20, Express 5, TypeScript 5.3 |
| **Database** | PostgreSQL 16, Prisma ORM |
| **Frontend** | Angular 17, Tailwind CSS |
| **Auth** | JWT, OAuth 2.0 (Google, GitHub) |
| **Cache** | Redis 7 |
| **Queue** | BullMQ |
| **Testing** | Jest, Supertest, Playwright |

## Quick Start

### Prerequisites

- Node.js >= 20
- PostgreSQL >= 15
- Redis >= 7
- npm >= 10

### Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/taskflow.git
cd taskflow

# Install dependencies
npm install

# Copy environment file
cp .env.example .env

# Edit .env with your configuration (see Configuration section)

# Run database migrations
npm run db:migrate

# Seed initial data (optional)
npm run db:seed

# Start development server
npm run dev
```

The application will be available at `http://localhost:3000`.

## Configuration

Create a `.env` file based on `.env.example`:

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `NODE_ENV` | Environment (development/production) | Yes | development |
| `PORT` | Server port | No | 3000 |
| `DATABASE_URL` | PostgreSQL connection string | Yes | - |
| `REDIS_URL` | Redis connection string | Yes | - |
| `JWT_SECRET` | Secret for JWT signing (min 32 chars) | Yes | - |
| `JWT_EXPIRES_IN` | Token expiration | No | 7d |
| `GOOGLE_CLIENT_ID` | Google OAuth client ID | No | - |
| `STRIPE_SECRET_KEY` | Stripe API key | No | - |

<details>
<summary>📋 Full environment variables list</summary>

```env
# Server
NODE_ENV=development
PORT=3000
API_PREFIX=/api/v1

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/taskflow

# Redis
REDIS_URL=redis://localhost:6379

# Authentication
JWT_SECRET=your-super-secret-key-at-least-32-characters
JWT_EXPIRES_IN=7d
REFRESH_TOKEN_EXPIRES_IN=30d

# OAuth (optional)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

# Email (optional)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=
SMTP_PASS=

# Stripe (optional)
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
```

</details>

## Usage

### Creating a Project

```bash
curl -X POST http://localhost:3000/api/v1/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{{ "{" }}"name": "Website Redesign", "description": "Client project"{{ "}" }}'
```

### Starting Time Tracking

```bash
curl -X POST http://localhost:3000/api/v1/time-entries/start \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{{ "{" }}"taskId": "task-123"{{ "}" }}'
```

See [API Documentation](docs/API.md) for complete reference.

## Testing

```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suite
npm test -- --grep "UserService"

# Run E2E tests
npm run test:e2e
```

## Deployment

See [Deployment Guide](docs/DEPLOYMENT.md) for detailed instructions.

### Quick Deploy with Docker

```bash
# Build image
docker build -t taskflow:latest .

# Run with docker-compose
docker-compose up -d
```

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Roadmap

- [x] Core task management
- [x] Time tracking
- [x] Basic invoicing
- [ ] Mobile app (React Native)
- [ ] AI-powered task suggestions
- [ ] Advanced reporting
- [ ] Zapier integration

## License

This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.

## Support

- 📖 [Documentation](https://docs.taskflow.dev)
- 💬 [Discord Community](https://discord.gg/taskflow)
- 🐛 [Issue Tracker](https://github.com/yourusername/taskflow/issues)
- 📧 [Email Support](mailto:support@taskflow.dev)

---

<p align="center">
  Made with ❤️ by <a href="https://github.com/yourusername">Your Name</a>
</p>

API Documentation con OpenAPI

La documentazione API dovrebbe essere generata automaticamente dal codice quando possibile, ma Copilot può aiutare a scrivere le specifiche OpenAPI iniziali o ad arricchirle.

Prompt per OpenAPI Spec

Generate OpenAPI 3.1 specification for these endpoints:

RESOURCE: Tasks
BASE PATH: /api/v1/tasks

ENDPOINTS:
1. POST /tasks - Create task
2. GET /tasks - List tasks (paginated, filterable)
3. GET /tasks/:id - Get task by ID
4. PATCH /tasks/:id - Update task
5. DELETE /tasks/:id - Delete task
6. POST /tasks/:id/start - Start time tracking
7. POST /tasks/:id/stop - Stop time tracking

TASK SCHEMA:
- id: UUID (readonly)
- title: string (required, 3-200 chars)
- description: string (optional, max 5000)
- status: enum [todo, in_progress, done]
- priority: enum [low, medium, high]
- dueDate: ISO8601 datetime (optional)
- projectId: UUID (required)
- assigneeId: UUID (optional)
- estimatedHours: number (optional)
- actualHours: number (readonly, computed)
- createdAt: datetime (readonly)
- updatedAt: datetime (readonly)

INCLUDE:
- Complete request/response schemas
- All query parameters for list endpoint
- Authentication (Bearer token)
- Error responses (400, 401, 403, 404, 500)
- Example values for all fields
- Descriptions in Italian for public docs

Esempio OpenAPI Completo

openapi: 3.1.0
info:
  title: TaskFlow API
  description: |
    API per la gestione di task e progetti.

    ## Autenticazione
    Tutte le richieste richiedono un token JWT nel header Authorization:
    ```
    Authorization: Bearer <token>
    ```

    ## Rate Limiting
    - 100 richieste/minuto per utente autenticato
    - 10 richieste/minuto per IP non autenticato
  version: 1.0.0
  contact:
    email: api@taskflow.dev

servers:
  - url: https://api.taskflow.dev/v1
    description: Production
  - url: https://staging-api.taskflow.dev/v1
    description: Staging
  - url: http://localhost:3000/api/v1
    description: Local Development

tags:
  - name: Tasks
    description: Gestione dei task

paths:
  /tasks:
    post:
      tags: [Tasks]
      summary: Crea un nuovo task
      description: Crea un task associato a un progetto.
      operationId: createTask
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
            example:
              title: "Implementare login OAuth"
              description: "Aggiungere supporto per Google e GitHub OAuth"
              projectId: "proj-123"
              priority: "high"
              dueDate: "2025-02-15T10:00:00Z"
      responses:
        '201':
          description: Task creato con successo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

    get:
      tags: [Tasks]
      summary: Lista dei task
      description: |
        Recupera una lista paginata di task con filtri opzionali.
        I risultati sono ordinati per data di creazione decrescente.
      operationId: listTasks
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          description: Numero pagina (1-based)
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Elementi per pagina
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: projectId
          in: query
          description: Filtra per progetto
          schema:
            type: string
            format: uuid
        - name: status
          in: query
          description: Filtra per stato
          schema:
            type: string
            enum: [todo, in_progress, done]
        - name: priority
          in: query
          description: Filtra per priorità
          schema:
            type: string
            enum: [low, medium, high]
        - name: assigneeId
          in: query
          description: Filtra per assegnatario
          schema:
            type: string
            format: uuid
        - name: search
          in: query
          description: Cerca nel titolo e descrizione
          schema:
            type: string
            minLength: 2
      responses:
        '200':
          description: Lista task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskListResponse'

  /tasks/{{ '{' }}taskId{{ '}' }}:
    parameters:
      - name: taskId
        in: path
        required: true
        description: ID univoco del task
        schema:
          type: string
          format: uuid

    get:
      tags: [Tasks]
      summary: Dettaglio task
      operationId: getTask
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Task trovato
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags: [Tasks]
      summary: Aggiorna task
      description: Aggiorna uno o più campi del task.
      operationId: updateTask
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskRequest'
      responses:
        '200':
          description: Task aggiornato
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags: [Tasks]
      summary: Elimina task
      description: Soft delete - il task viene marcato come eliminato.
      operationId: deleteTask
      security:
        - bearerAuth: []
      responses:
        '204':
          description: Task eliminato
        '404':
          $ref: '#/components/responses/NotFound'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    CreateTaskRequest:
      type: object
      required: [title, projectId]
      properties:
        title:
          type: string
          minLength: 3
          maxLength: 200
          description: Titolo del task
        description:
          type: string
          maxLength: 5000
          description: Descrizione dettagliata
        projectId:
          type: string
          format: uuid
          description: ID del progetto
        priority:
          type: string
          enum: [low, medium, high]
          default: medium
        status:
          type: string
          enum: [todo, in_progress, done]
          default: todo
        dueDate:
          type: string
          format: date-time
        assigneeId:
          type: string
          format: uuid
        estimatedHours:
          type: number
          minimum: 0

    UpdateTaskRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 3
          maxLength: 200
        description:
          type: string
          maxLength: 5000
        priority:
          type: string
          enum: [low, medium, high]
        status:
          type: string
          enum: [todo, in_progress, done]
        dueDate:
          type: string
          format: date-time
        assigneeId:
          type: string
          format: uuid

    Task:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        title:
          type: string
        description:
          type: string
        projectId:
          type: string
          format: uuid
        status:
          type: string
          enum: [todo, in_progress, done]
        priority:
          type: string
          enum: [low, medium, high]
        dueDate:
          type: string
          format: date-time
        assigneeId:
          type: string
          format: uuid
        estimatedHours:
          type: number
        actualHours:
          type: number
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true

    TaskResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Task'

    TaskListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Task'
        meta:
          type: object
          properties:
            page:
              type: integer
            limit:
              type: integer
            total:
              type: integer
            totalPages:
              type: integer

    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string

  responses:
    ValidationError:
      description: Errore di validazione
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: VALIDATION_ERROR
              message: Dati non validi
              details:
                - field: title
                  message: Il titolo deve avere almeno 3 caratteri

    Unauthorized:
      description: Non autenticato
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Token mancante o non valido

    Forbidden:
      description: Accesso negato
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: FORBIDDEN
              message: Non hai i permessi per questa operazione

    NotFound:
      description: Risorsa non trovata
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Task non trovato

Architecture Decision Records (ADR)

Gli ADR documentano le decisioni architetturali importanti, il contesto in cui sono state prese e le alternative considerate. Sono fondamentali per capire il "perché" delle scelte tecniche.

Prompt per ADR

Create an Architecture Decision Record (ADR) for this decision:

DECISION: Usare PostgreSQL come database invece di MongoDB
CONTEXT: Stiamo costruendo un task management SaaS
DATE: 2025-01-30

FACTORS CONSIDERED:
1. Dati fortemente relazionali (users, projects, tasks, time entries)
2. Need for complex queries and reporting
3. ACID compliance for financial data (invoicing)
4. Team familiarity with SQL
5. Future scaling needs

ALTERNATIVES:
1. MongoDB - NoSQL, flexible schema
2. MySQL - Traditional RDBMS
3. CockroachDB - Distributed SQL

Follow the standard ADR template with:
- Title (ADR-XXX: Brief description)
- Status
- Context
- Decision
- Alternatives Considered (with pros/cons)
- Consequences (positive, negative, risks)
- Notes/Follow-up

Template ADR Completo

# ADR-001: Scelta di PostgreSQL come Database Primario

## Status
**Accepted** - 2025-01-30

## Context

Stiamo progettando il backend per TaskFlow, una piattaforma SaaS per la gestione
di task e progetti rivolta a freelancer e piccoli team. Il sistema deve gestire:

- **Utenti e team:** Relazioni N:M con ruoli e permessi
- **Progetti e task:** Struttura gerarchica, stati, priorità
- **Time tracking:** Sessioni di lavoro con timestamp precisi
- **Fatturazione:** Dati finanziari che richiedono precisione e audit trail
- **Analytics:** Query complesse per report e dashboard

### Requisiti chiave

1. **Integrità dei dati:** I dati finanziari richiedono transazioni ACID
2. **Query complesse:** Report che aggregano dati da multiple tabelle
3. **Scalabilità verticale:** MVP con 1000 utenti, target 50.000 in 18 mesi
4. **Performance:** Dashboard deve caricare in <500ms
5. **Costo:** Budget limitato per infrastruttura

### Vincoli

- Team di 2 sviluppatori con esperienza SQL
- Timeline MVP: 3 mesi
- Hosting cloud (preferibilmente managed)

## Decision

Utilizziamo **PostgreSQL 16** come database primario, con **Prisma ORM** per l'accesso dati.

### Motivazioni

1. **Modello relazionale:** I nostri dati sono fortemente relazionali (users → projects → tasks → time_entries)
2. **ACID compliance:** Transazioni atomiche per operazioni finanziarie
3. **Query potenti:** JOIN, aggregazioni, window functions per analytics
4. **JSONB:** Flessibilità per metadati senza sacrificare la struttura
5. **Maturità:** 30+ anni di sviluppo, documentazione eccellente, community attiva
6. **Tooling:** Prisma ha supporto first-class, pgAdmin per admin, pg_dump per backup
7. **Managed options:** Disponibile su tutti i cloud provider (Supabase, Neon, RDS)

## Alternatives Considered

### MongoDB

| Aspect | Pro | Contro |
|--------|-----|--------|
| Schema | Flessibile, evolve facilmente | Meno controllo integrità |
| Query | Semplici su singoli documenti | JOIN costose (lookup) |
| Scale | Horizontal scaling nativo | Overkill per le nostre esigenze |
| Team | - | Nessuna esperienza |
| Cost | - | Atlas costoso per feature enterprise |

**Decisione:** Scartato. I nostri dati sono relazionali, MongoDB aggiungerebbe complessità inutile.

### MySQL 8

| Aspect | Pro | Contro |
|--------|-----|--------|
| Familiarità | Molto diffuso | Supporto JSON meno maturo |
| Performance | Buona per OLTP | Window functions più limitate |
| Cost | Economico | - |
| Tooling | Prisma supporta | - |

**Decisione:** Valida alternativa, ma PostgreSQL offre feature più avanzate (JSONB, array, full-text search nativo).

### CockroachDB

| Aspect | Pro | Contro |
|--------|-----|--------|
| Scale | Distributed di default | Complessità operativa |
| Resilience | Multi-region built-in | Overkill per MVP |
| Compatibility | PostgreSQL wire protocol | Alcune differenze |
| Cost | - | Tier gratuito limitato |

**Decisione:** Scartato per MVP. Potrebbe essere considerato per scale-up futuro.

## Consequences

### Positive

1. **Query potenti:** Possiamo costruire analytics complesse senza caching layer
2. **Integrità garantita:** Foreign keys, constraints, transazioni
3. **Developer experience:** Prisma migrations, type safety
4. **Ecosistema:** Estensioni (PostGIS se servirà geo), pgvector per AI
5. **Costo prevedibile:** Managed PostgreSQL a prezzi ragionevoli

### Negative

1. **Scaling orizzontale:** Richiede più lavoro (read replicas, sharding manuale)
2. **Schema rigido:** Migrazioni necessarie per modifiche strutturali
3. **Vendor lock-in:** Alcune feature PG-specific (JSONB operators)

### Risks

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| Performance issues at scale | Medium | High | Monitoring, query optimization, read replicas |
| Vendor lock-in | Low | Medium | Usare SQL standard dove possibile |
| Team learning curve | Low | Low | Documentazione interna, pair programming |

## Implementation Notes

### Hosting

- **Development:** Docker locale
- **Staging:** Supabase (tier gratuito)
- **Production:** Supabase Pro o Neon (da valutare costi)

### Backup Strategy

- Point-in-time recovery abilitato
- Daily snapshots automatici
- Test restore mensile

### Monitoring

- Query performance con pg_stat_statements
- Connection pooling con PgBouncer
- Alerting su slow queries (>1s)

## Follow-up Actions

- [ ] Setup Prisma con PostgreSQL
- [ ] Configurare docker-compose per development
- [ ] Definire schema iniziale per User, Project, Task
- [ ] Creare monitoring dashboard

## Related Decisions

- ADR-002: Scelta ORM (Prisma)
- ADR-003: Caching strategy (Redis)

## References

- [PostgreSQL vs MongoDB 2025](https://example.com/comparison)
- [Prisma PostgreSQL Guide](https://www.prisma.io/docs/concepts/database-connectors/postgresql)
- [Supabase Pricing](https://supabase.com/pricing)

---
**Author:** Federico Calò
**Reviewers:** Team Lead
**Last Updated:** 2025-01-30

JSDoc e Code Documentation

La documentazione inline aiuta gli sviluppatori a capire il codice senza dover leggere l'implementazione completa.

Prompt per JSDoc

Add comprehensive JSDoc documentation to this TypeScript code:

```typescript
[PASTE CODE HERE]
```

INCLUDE FOR EACH FUNCTION/METHOD:
1. Brief description (one sentence)
2. Detailed explanation (if complex)
3. @param for each parameter with type and description
4. @returns with type and description
5. @throws for each exception that can be thrown
6. @example with realistic usage
7. @see for related functions
8. @since version number
9. @deprecated if applicable

STYLE:
- Use imperative mood ("Creates a user" not "This creates a user")
- Document edge cases in description
- Include validation rules in @param descriptions
- Add @remarks for implementation notes

Esempio JSDoc Completo

/**
 * Service per la gestione degli utenti.
 *
 * Gestisce operazioni CRUD, autenticazione e autorizzazione per gli utenti.
 * Tutte le password sono hashate con bcrypt prima del salvataggio.
 *
 * @remarks
 * Questo service non gestisce direttamente i token JWT. Vedi {@link AuthService}
 * per le operazioni di autenticazione.
 *
 * @example
 * ```typescript
 * const userService = new UserService(userRepository, emailService);
 *
 * // Creare un nuovo utente
 * const user = await userService.create({
 *   name: 'Mario Rossi',
 *   email: 'mario@example.com',
 *   password: 'SecurePass123!'
 * });
 *
 * // Aggiornare un utente
 * await userService.update(user.id, { name: 'Mario Bianchi' });
 * ```
 *
 * @since 1.0.0
 */
export class UserService {
  /**
   * Crea una nuova istanza di UserService.
   *
   * @param userRepository - Repository per l'accesso ai dati utente
   * @param emailService - Service per l'invio di email
   */
  constructor(
    private readonly userRepository: UserRepository,
    private readonly emailService: EmailService
  ) {}

  /**
   * Crea un nuovo utente nel sistema.
   *
   * Valida i dati in input, verifica che l'email non sia già registrata,
   * hash della password e invio email di benvenuto.
   *
   * @param dto - Dati per la creazione dell'utente
   * @param dto.name - Nome completo (2-100 caratteri)
   * @param dto.email - Email valida e unica nel sistema
   * @param dto.password - Password (min 8 char, 1 maiuscola, 1 numero, 1 speciale)
   *
   * @returns L'utente creato (senza password)
   *
   * @throws {ValidationError} Se i dati non superano la validazione
   * @throws {ConflictError} Se l'email è già registrata
   * @throws {ServiceError} Se l'invio email fallisce (utente creato comunque)
   *
   * @example
   * ```typescript
   * try {
   *   const user = await userService.create({
   *     name: 'Mario Rossi',
   *     email: 'mario@example.com',
   *     password: 'SecurePass123!'
   *   });
   *   console.log(`Utente creato: ${user.id}`);
   * } catch (error) {
   *   if (error instanceof ConflictError) {
   *     console.error('Email già registrata');
   *   }
   * }
   * ```
   *
   * @see {@link UserService.update} per aggiornare un utente esistente
   * @since 1.0.0
   */
  async create(dto: CreateUserDto): Promise<User> {
    // Implementation...
  }

  /**
   * Recupera un utente per ID.
   *
   * @param id - UUID dell'utente
   *
   * @returns L'utente trovato
   *
   * @throws {ValidationError} Se l'ID non è un UUID valido
   * @throws {NotFoundError} Se l'utente non esiste o è stato eliminato
   *
   * @example
   * ```typescript
   * const user = await userService.findById('550e8400-e29b-41d4-a716-446655440000');
   * ```
   *
   * @since 1.0.0
   */
  async findById(id: string): Promise<User> {
    // Implementation...
  }

  /**
   * Aggiorna un utente esistente.
   *
   * Aggiorna solo i campi forniti. I campi non inclusi nel DTO rimangono invariati.
   *
   * @param id - UUID dell'utente da aggiornare
   * @param dto - Campi da aggiornare (tutti opzionali)
   * @param dto.name - Nuovo nome (2-100 caratteri)
   * @param dto.email - Nuova email (deve essere unica)
   * @param dto.password - Nuova password (verrà hashata)
   *
   * @returns L'utente aggiornato
   *
   * @throws {NotFoundError} Se l'utente non esiste
   * @throws {ConflictError} Se la nuova email è già in uso da un altro utente
   * @throws {ValidationError} Se i dati non superano la validazione
   *
   * @remarks
   * L'aggiornamento dell'email non richiede verifica email. Per implementazioni
   * più sicure, considerare un flusso di verifica separato.
   *
   * @example
   * ```typescript
   * // Aggiorna solo il nome
   * const updated = await userService.update(userId, { name: 'Nuovo Nome' });
   *
   * // Aggiorna più campi
   * const updated = await userService.update(userId, {
   *   name: 'Nuovo Nome',
   *   email: 'nuova@email.com'
   * });
   * ```
   *
   * @since 1.0.0
   */
  async update(id: string, dto: UpdateUserDto): Promise<User> {
    // Implementation...
  }

  /**
   * Elimina un utente (soft delete).
   *
   * L'utente viene marcato come eliminato ma i dati vengono mantenuti per
   * audit e compliance. Non è possibile fare login dopo la soft delete.
   *
   * @param id - UUID dell'utente da eliminare
   *
   * @throws {NotFoundError} Se l'utente non esiste
   * @throws {ForbiddenError} Se si tenta di eliminare l'ultimo admin
   *
   * @remarks
   * Per eliminare definitivamente i dati (GDPR), usare {@link hardDelete}.
   *
   * @example
   * ```typescript
   * await userService.softDelete(userId);
   * // L'utente non può più fare login
   * ```
   *
   * @see {@link UserService.hardDelete} per eliminazione definitiva
   * @since 1.0.0
   */
  async softDelete(id: string): Promise<void> {
    // Implementation...
  }
}

Changelog

Un changelog ben strutturato comunica chiaramente cosa è cambiato tra le versioni. Segue il formato "Keep a Changelog".

Prompt per Changelog

Generate a changelog entry for version 1.2.0.

CHANGES MADE:
1. Added email notification system for task deadlines
2. Added user preferences page
3. Fixed bug where tasks could be duplicated when clicking save twice
4. Fixed memory leak in websocket connections
5. Improved task filtering performance (50% faster)
6. Updated error messages for better UX
7. Removed deprecated v1 API endpoints

Follow Keep a Changelog format with sections:
- Added (new features)
- Changed (changes in existing functionality)
- Deprecated (features that will be removed)
- Removed (removed features)
- Fixed (bug fixes)
- Security (security fixes)

Esempio CHANGELOG.md

# Changelog

All notable changes to TaskFlow will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Dark mode support (#234)
- Keyboard shortcuts for common actions

### Changed
- Improved onboarding flow

---

## [1.2.0] - 2025-02-01

### Added
- **Email notifications** for task deadlines - Users now receive email reminders
  24 hours and 1 hour before task due dates
- **User preferences page** - Customize notification settings, timezone, and language
- Export tasks to CSV format

### Changed
- Improved task filtering performance by 50% through database query optimization
- Updated error messages to be more user-friendly and actionable
- Redesigned task card layout for better information density

### Fixed
- Fixed bug where tasks could be duplicated when clicking save button rapidly (#187)
- Fixed memory leak in websocket connections that caused browser slowdown (#192)
- Fixed timezone handling in due date display (#195)

### Removed
- Removed deprecated v1 API endpoints (deprecated in 1.0.0)

---

## [1.1.0] - 2025-01-15

### Added
- **Task labels and categories** - Organize tasks with custom colored labels
- **Export to CSV** - Download task data for external analysis
- Bulk task operations (archive, delete, move)

### Changed
- Increased maximum task description length from 2000 to 5000 characters
- Improved mobile responsiveness of kanban board

### Fixed
- Fixed issue where completed tasks weren't syncing across devices (#156)
- Fixed search not finding tasks with special characters (#161)

### Security
- Updated dependencies to patch CVE-2025-1234 in express-validator

---

## [1.0.0] - 2025-01-01

### Added
- Initial release
- User authentication (email/password, Google OAuth)
- Project management with team collaboration
- Task management with drag-and-drop kanban board
- Time tracking with one-click timer
- Basic reporting dashboard

---

[Unreleased]: https://github.com/username/taskflow/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/username/taskflow/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/username/taskflow/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/username/taskflow/releases/tag/v1.0.0

Best Practices per la Documentazione

Checklist Documentazione

Conclusione e Prossimi Passi

La documentazione è un investimento che paga dividendi enormi nel tempo. Riduce il tempo di onboarding, diminuisce le domande ripetitive, e rende il progetto più professionale e affidabile.

Copilot può generare una prima bozza di alta qualità, ma il contenuto deve essere verificato e personalizzato. L'AI non conosce i dettagli specifici del tuo progetto - tu sì.

Nel prossimo articolo vedremo come usare Copilot per il deploy e DevOps: Dockerfile multi-stage, Docker Compose, CI/CD con GitHub Actions, health checks e logging in produzione.