Indice

Tipi di documentazione

Segue una breve descrizione dei tipi di contributi alla documentazione accettati su amp.dev:

Esercitazioni introduttive

Le esercitazioni introduttive aiutano gli sviluppatori a farsi un'idea generale della tecnologia che stanno usando. Partono dai concetti di codifica e accompagnano lo sviluppatore fino alla realizzazione di un programma di esempio "Ciao Mondo" completo. Le esercitazioni introduttive mostrano come creare le varie funzionalità chiave di AMP tramite dettagliate procedure guidate. L'utilizzo combinato di esercitazioni introduttive con esempi di codice inline e/o campioni di codice scaricabili, che richiedono piccole modifiche da parte dello sviluppatore, è una buona pratica.

esempi amp.dev:

Cosa fanno	Cosa non fanno
Le esercitazioni introduttive forniscono una guida con brevi spiegazioni e piccoli passi.	Le esercitazioni introduttive non approfondiscono tutti gli aspetti del progetto. Ci sono molti modi di realizzare queste esercitazioni, ma il loro scopo non è quello di mostrare tutti i percorsi possibili, quanto quello di indicarne uno solo praticabile.
Forniscono un ambiente semplificato e strumenti di configurazione.	Non presuppongono che lo sviluppatore abbia familiarità con il prodotto né una notevole esperienza e capacità di codifica.
Forniscono esempi visivi dalla struttura semplice.	Non prevedono complicazioni fini a se stesse, a meno che l'esercitazione non riguardi esplicitamente lo stile.
Forniscono schermate di ogni passo delle procedure e una dimostrazione completa.	Non forniscono solo esempi di codifica.
Permettono di fare pratica. Indicano allo sviluppatore i punti da portare a termine.	Non dotano gli esempi di eccessive spiegazioni. Può essere una buona idea segnalare problemi relativi a guide o esercitazioni che non sembrano sufficientemente complete.

Esercitazioni avanzate

Le esercitazioni avanzate permettono agli sviluppatori di realizzare compiti specifici. Presuppongono che lo sviluppatore abbia una certa familiarità con AMP. Dovrebbero dare indicazioni su come realizzare un'esperienza, integrare funzionalità o affrontare le attività di implementazione.

esempi amp.dev:

Cosa fanno	Cosa non fanno
Le esercitazioni avanzate forniscono istruzioni guidate con un chiaro progetto finale.	Le esercitazioni avanzate non forniscono tutti i dettagli e concetti eccessivamente elaborati.
Forniscono esempi di codice normale o codice di avvio scaricabile. Inoltre, completano e rendono scaricabile il progetto finale.	Non forniscono esempi o processi alternativi per raggiungere il risultato finale.
Creano un ambiente plug and play.	Non contengono collegamenti a esercitazioni esterne di configurazione. Le esercitazioni dovrebbero essere autonome.

Guide introduttive

Le guide introduttive forniscono una panoramica delle informazioni pertinenti per iniziare a operare con AMP. Permettono di identificare le funzioni, descrivendo di cosa si tratta e indicandone chiaramente i risultati. Le guide introduttive presentano agli sviluppatori i requisiti di base della funzionalità in questione, senza esplicite indicazioni di implementazione. Per scrivere un'esercitazione, occorre tracciare una procedura guidata con esempi di codice. Per scrivere un documento di riferimento, occorre definire tutti gli elementi programmatici di un componente AMP.

esempi amp.dev:

Cosa fanno	Cosa non fanno
Le guide introduttive individuano gli argomenti coperti dal documento.	Le guide introduttive non forniscono procedure guidate.
Introducono funzionalità e concetti. Contengono collegamenti a documenti di riferimento per dettagli sull'utilizzo avanzato.	Non descrivono tutti i dettagli.
Forniscono esempi di codice ed esempi del mondo reale.	Non creano app complete. È preferibile includere collegamenti ad esempi e demo per fare ulteriore pratica.
Elencano gli usi tecnici e le restrizioni.	Non elencano tutti i possibili usi tecnici e la loro realizzazione

Guide concettuali

Le guide concettuali aiutano gli sviluppatori a comprendere più a fondo i sistemi AMP. Una guida concettuale è come una mappa topografica. Mostra i vari percorsi di un'area con informazioni quali le variazioni altimetriche, ma non indica un percorso specifico sul territorio. Descrive le funzioni e come agiscono, senza indicazioni vincolanti su come realizzarle.

esempi amp.dev:

Cosa fanno	Cosa non fanno
Le guide concettuali forniscono allo sviluppatore tutti gli elementi necessari per costruire una soluzione.	Le guide concettuali non guidano attivamente lo sviluppatore verso uno specifico stato finale.
Descrivono tutti gli aspetti degli argomenti trattati.	Non si concentrano su attività specifiche.
Comprendono strumenti visivi ausiliari, come diagrammi o schermate.	Non devono approfondire eccessivamente questo aspetto. Può essere utile richiedere assistenza per gli strumenti visivi ausiliari al [gruppo di lavoro di assistenza] (https://github.com/ampproject/wg-outreach).
Forniscono esempi di codice e collegamenti esterni ad altre guide.	Non forniscono versioni scaricabili di progetti finiti o fuori tema.

Documentazione di riferimento

La documentazione di riferimento elenca tutti gli elementi programmatici per i componenti AMP. Essa fornisce informazioni dettagliate sul comportamento di tali elementi ed è pensata per facilitarne la consultazione. La documentazione di riferimento dovrebbe contenere esempi di codice e dare dimostrazioni dei casi di utilizzo.

I documenti di riferimento amp.dev sono disponibili nel catalogo dei componenti AMP.

È possibile contribuire alla documentazione di riferimento AMP nell'archivio AMPHTML.

Cosa fanno	Cosa non fanno
I documenti di riferimento fanno uso di un linguaggio chiaro e conciso che spiega il funzionamento dei componenti.	I documenti di riferimento non descrivono procedure né implementano progetti.
Sono dotati di struttura che permette un'agevole esplorazione di titoli, intestazioni e sottotitoli.	I contenuti con sono raggruppati sotto titoli generici.
Forniscono frammenti di codice che dimostrano l'utilizzo del componente.	Non creano applicazioni demo complete.

Written by @CrystalOnScript