Passa al contenuto principale

Guida di stile dei contenuti

Tutti i livelli

La coerenza è ciò che rende affidabile un'opera di riferimento. Seguendo queste regole la tua PR supera la revisione senza intoppi.

Tono di voce​

  • Chiaro e diretto. Frasi brevi. Vai dritto al punto.
  • Amichevole, mai prolisso. Elimina "nel mondo frenetico di oggi". Rispetta il tempo del lettore.
  • Deciso, poi onesto. Indica per primo l'unico modo raccomandato, poi segnala alternative e compromessi.
  • Esempi più che teoria. Mostra uno snippet o un caso concreto; non limitarti a descrivere.
  • Inglese americano.

Struttura di una pagina​

---
sidebar_position: 2
title: "Your Page Title"
description: "One sentence for search and previews."
---

<LevelBadge level="beginner" />

A one or two sentence intro that states what the reader will get.

## Sections with ## headings
...

## Next
- 2–4 links to related pages
  • Inizia con il badge di livello (beginner | intermediate | advanced | all). I componenti sono globali — non importarli.
  • Termina con un elenco "Avanti" / "Correlati" di 2–4 link interni.
  • Usa le admonition (:::tip, :::warning, :::note, :::info) per dare enfasi, con parsimonia.

Le due regole inderogabili​

:::warning Non negoziabile

  1. Cita le fonti per i fatti volatili. Nomi dei modelli, prezzi, limiti, flag esatti, funzionalità beta → collega la fonte ufficiale e aggiungi <VerifyNote lastVerified="YYYY-MM-DD" source="…">. Non scrivere mai a codice fisso i fatti sui modelli — collega la tabella dei modelli. Dettagli: Verifica dei fatti.
  2. Non inventare. Niente statistiche, citazioni, API o funzionalità inventate. Se non sei sicuro, dichiaralo o segnala con [verify]. :::

Opinione vs ufficiale​

  • Siamo decisi — è questo il valore. Raccomanda, non limitarti a elencare.
  • Ma la documentazione ufficiale è la fonte di verità. Rimettiti ad essa, collegala e non contraddirla mai silenziosamente.

Insidie di MDX​

  • Le parentesi graffe {like this} nella prosa vengono interpretate come codice da MDX — mettile tra backtick o in blocchi di codice, oppure usa le [parentesi quadre] negli esempi.
  • Testa in locale: npm run build deve passare (fallisce sui link rotti).

Avanti​