Panoramica
Questa guida fornisce linee guida generali per la scrittura di tutorial di Google Earth Engine. L'obiettivo è semplificare la creazione di tutorial di alta qualità, chiari, concisi e facilmente comprensibili per l'intera community di Earth Engine.
I modelli di tutorial riportati di seguito fungono anche da guida aggiuntiva per aiutarti a iniziare a creare i tuoi tutorial. I dettagli su come utilizzare i modelli per iniziare sono disponibili in Scrivere un tutorial.
Inoltre, la Guida di stile per i tutorial della community della piattaforma Google Cloud fornisce un riferimento prezioso per la scrittura di tutorial end-to-end per un pubblico ampio, mentre la Guida di stile di JavaScript di Google descrive in dettaglio lo stile consigliato per l'utilizzo negli esempi di codice JavaScript. I revisori possono fare riferimento a queste guide durante la revisione dell'invio.
Linee guida generali
- Sii breve.
- Non ripeterti.
- Non dire la stessa cosa due volte (anche se formulata in modo diverso).
- Segna periodicamente i progressi.
- Includi immagini e testo nei punti chiave del tutorial in modo che l'utente sappia di essere sulla strada giusta. Utilizza questa categoria con attenzione.
- Se possibile, usa la forma attiva.
- "Quando l'utente modifica il valore", non "quando il valore viene modificato".
- Eccezione: è consentito utilizzare la forma passiva quando è necessario fare uno sforzo per utilizzare la forma attiva o se l'attore è ovvio o non pertinente ("viene restituita una GIF animata" anziché "Earth Engine restituisce una GIF animata").
- Attieniti ai fatti.
- Evita i superlativi ("questo è il metodo migliore e più veloce").
- Evita di promuovere prodotti o servizi.
- Evita argomenti controversi.
- Includi citazioni e URL quando fai riferimento a metodi, set di dati e analisi specifici.
- Rendi il tutorial autonomo.
- Cerca di non fare affidamento su librerie speciali al di fuori dell'API o su set di dati non presenti nel catalogo di dati pubblici di Earth Engine.
- Se fornisci dati o algoritmi aggiuntivi, condividili solo se hai l'autorizzazione a farlo. Includi tutte le licenze e le attribuzioni richieste.
- Prova il codice.
- Assicurati di eseguire e testare tutti gli esempi di codice inclusi prima di inviare l'articolo per la revisione.
Intestazioni dei file dei tutorial
Se crei e invii tutorial della community manualmente senza utilizzare i modelli forniti in Scrivere un tutorial, dovrai aggiungere manualmente l'intestazione dei metadati e della licenza appropriata all'inizio del file. Seleziona il formato desiderato per visualizzare un modello che può essere copiato nel tuo tutorial:
Markdown
Aggiungi quanto segue all'inizio del documento. Nessuno spazio bianco o altro carattere deve precedere l'intestazione:
---
title: Your tutorial title
description: A short description of the tutorial, all on one line with no carriage returns.
author: your-github-username
tags: comma-separated, lowercase, list, of, related, keywords
date_published: YYYY-MM-DD
---
<!--
Copyright 2023 The Google Earth Engine Community Authors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
Assicurati di sostituire i campi del modello appropriati prima di inviare il tutorial per la revisione.
Colab
Aggiungi quanto segue a una cella di codice all'inizio del blocco note:
#@title Copyright 2023 The Earth Engine Community Authors { display-mode: "form" }
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
Modelli di tutorial
Markdown
Se hai familiarità con git e GitHub, puoi utilizzare il codice riportato di seguito come modello per iniziare:
---
title: Your tutorial title
description: A short description of the tutorial, all on one line with no carriage returns.
author: your-github-username
tags: comma-separated, lowercase, list, of, related, keywords
date_published: YYYY-MM-DD
---
<!--
Copyright 2023 The Google Earth Engine Community Authors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
In a few sentences, describe what the user is going to learn. Be sure to include
_concise_ background information; only include what's helpful and relevant.
When in doubt, leave it out!
## Section heading 1
Break up your tutorial into manageable sections.
With one or more paragraphs, separated by a blank line.
Inside your sections, you can also:
1. Use numbered lists
1. ..when the order..
1. ..of items is important.
And:
- This is a bulleted list.
- Use bulleted lists when items are not strictly ordered.
..and even:
Use | tables | to organize | content
------- | -------- | ----------- | -------
Your | tables | can | also
contain | multiple | rows | ...
## Section heading 2
Use separate sections for related, but discrete, groups of steps.
Use code blocks to show users how to do something after describing it:
```js
// Use comments to describe details that can't be easily expressed in code.
// Always try making code more self descriptive before adding a comment.
// Similarly, avoid repeating verbatim what's already said in code
// (e.g., "assign ImageCollection to variable 'coll'").
var coll = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA');
```
### Use subsections if appropriate
Consider breaking longer sections that cover multiple topics or span multiple
pages into subsections.
In alternativa, il modello precedente può essere aperto direttamente nell'editor di file basato sul web di GitHub seguendo le istruzioni riportate in Scrivere un tutorial.
Consulta Scrivere un tutorial per informazioni importanti su come proporre, creare e inviare tutorial.
Colab
Per creare un nuovo blocco note Colab utilizzando il modello di stile consigliato, fai clic qui:
Verrà aperto un blocco note contenente le istruzioni per la creazione e l'invio del tutorial. Consulta Scrivere un tutorial per informazioni importanti sulla proposta, sulla creazione e sul processo di invio.