📝 Guida alla Scrittura della Documentazione

Questa guida ti aiuterà a scrivere documentazione chiara e coerente per il progetto Elerama Frontend.

🎯 Principi Base

1. Chiarezza: Scrivi in modo semplice e diretto
2. Esempi: Includi sempre esempi di codice pratici
3. Aggiornamento: Aggiorna i docs quando modifichi il codice
4. Organizzazione: Usa sezioni e sottosezioni logiche

📂 Struttura dei File

Organizza i file per argomento:

docs/
├── auth/           # Tutto sull'autenticazione
├── cart/           # Gestione carrello
├── api/            # Documentazione API
├── testing/        # Guide ai test
└── ...

✍️ Formato Markdown

Frontmatter (opzionale)

Aggiungi metadati all'inizio del file:

---
title: Titolo della Pagina
description: Breve descrizione per SEO
---

Titoli

# Titolo Principale (H1) - Solo uno per pagina

## Sezione (H2)

### Sottosezione (H3)

#### Paragrafo (H4)

Blocchi di Codice

Usa la sintassi con linguaggio specificato:

```typescript
// Codice TypeScript
const example = "hello";
```

Aggiungi evidenziazione delle righe:

```typescript{2,4-6}
// Riga normale
const highlighted = true; // Evidenziata
// Riga normale
const block = {
  also: "highlighted"
};
```

Custom Containers

VitePress supporta container speciali:

::: tip SUGGERIMENTO
Questo è un suggerimento utile!
:::

::: warning ATTENZIONE
Fai attenzione a questo aspetto!
:::

::: danger PERICOLO
Questo può causare problemi!
:::

::: details Clicca per espandere
Contenuto nascosto che si espande al click
:::

Link

<!-- Link interno (relativo) -->
[Guida Autenticazione](./auth/authentication.md)

<!-- Link a sezione -->
[Vai alla sezione](#titolo-sezione)

<!-- Link esterno -->
[VitePress](https://vitepress.dev/)

Tabelle

| Funzione | Descrizione | Esempio |
|----------|-------------|---------|
| `login()` | Login utente | `await login(credentials)` |
| `logout()` | Logout utente | `await logout()` |

Badge

<Badge type="tip" text="Nuovo" />
<Badge type="warning" text="Deprecato" />
<Badge type="danger" text="Breaking Change" />

Emoji

Usa emoji per rendere la documentazione più amichevole:

• 🚀 Per quick start, deployment
• ✅ Per checklist, best practices
• ⚠️ Per warning, note importanti
• 💡 Per tips, suggerimenti
• 📝 Per note, documentazione
• 🔧 Per configurazione
• 🐛 Per bug, problemi
• 🎨 Per UI, design

📋 Template per Nuove Pagine

Template Feature

---
title: Nome Feature
description: Breve descrizione della feature
---

# Nome Feature

Breve introduzione alla feature e quando usarla.

## 🎯 Scopo

Spiega cosa fa questa feature e perché è utile.

## 🚀 Quick Start

Esempio minimo per iniziare subito:

\`\`\`typescript
// Codice esempio
\`\`\`

## 📖 Guida Completa

### Installazione/Setup

Passi per configurare la feature.

### Utilizzo Base

\`\`\`typescript
// Esempio base
\`\`\`

### Utilizzo Avanzato

\`\`\`typescript
// Esempio avanzato
\`\`\`

## ⚙️ Configurazione

Opzioni disponibili e come configurarle.

## 🧪 Testing

Come testare questa feature.

## ⚠️ Note Importanti

Aspetti da tenere in considerazione.

## 📚 Riferimenti

- [Link risorsa 1]()
- [Link risorsa 2]()

Template API

# API: Nome API

## Endpoint

\`\`\`
GET /api/endpoint
\`\`\`

## Parametri

| Nome | Tipo | Required | Descrizione |
|------|------|----------|-------------|
| `id` | `string` | ✅ | ID dell'elemento |

## Response

\`\`\`typescript
interface Response {
  data: string;
  success: boolean;
}
\`\`\`

## Esempio

\`\`\`typescript
const result = await apiRequest('/api/endpoint', {
  params: { id: '123' }
});
\`\`\`

## Errori

| Codice | Messaggio | Descrizione |
|--------|-----------|-------------|
| 404 | Not Found | Elemento non trovato |

🎨 Best Practices

DO ✅

• Esempi reali: Usa esempi dal codice reale del progetto
• Coerenza: Mantieni lo stesso stile in tutta la documentazione
• Testing: Testa gli esempi per assicurarti che funzionino
• Aggiornamenti: Aggiorna i docs insieme al codice
• Screenshots: Aggiungi immagini quando utili (in docs/public/images/)

DON'T ❌

• Non duplicare: Non ripetere informazioni presenti altrove
• Non essere vago: Sii specifico e preciso
• Non dimenticare: Non lasciare TODO o esempi incompleti
• Non complicare: Evita spiegazioni troppo complesse

🔍 Revisione

Prima di committare la documentazione:

• [ ] Il titolo è chiaro e descrittivo?
• [ ] Gli esempi di codice funzionano?
• [ ] I link sono corretti?
• [ ] Il formato è coerente?
• [ ] La grammatica è corretta?
• [ ] È facile da capire per un nuovo sviluppatore?

📊 Sidebar

Quando aggiungi una nuova pagina, ricordati di aggiungerla in docs/.vitepress/config.ts:

sidebar: [
  {
    text: 'Categoria',
    items: [
      { text: 'Nuova Pagina', link: '/categoria/nuova-pagina' }
    ]
  }
]

🚀 Preview Locale

Avvia sempre il server locale per verificare che tutto sia corretto:

npm run docs:dev

---

Ricorda: La documentazione è importante quanto il codice!