Panoramica
Questa guida fornisce linee guida generali per la scrittura dei tuoi tutorial di Google Earth Engine. L'obiettivo è semplificare la creazione di tutorial di alta qualità che siano 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 Scrittura di un tutorial.
Inoltre, la guida di stile per i tutorial della community Google Cloud fornisce un riferimento prezioso per la scrittura di tutorial end-to-end per un pubblico ampio, mentre la guida di stile di Google per JavaScript descrive in dettaglio lo stile consigliato per l'utilizzo negli esempi di codice JavaScript. I revisori potrebbero fare riferimento a queste guide durante l'esame dei contenuti inviati.
Linee guida generali
- Sii breve.
- Non ripeterti.
- Non ripetere lo stesso concetto due volte (anche se con parole diverse).
- Contrassegna 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, utilizza la forma attiva.
- "Quando l'utente modifica il valore", non "quando il valore viene modificato".
- Eccezione: è possibile utilizzare la forma passiva quando l'uso della forma attiva risulta forzato 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 è al 100% 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.
- Crea un tutorial autonomo.
- Cerca di non fare affidamento su librerie speciali esterne all'API o su set di dati non presenti nel Data Catalog pubblico di Earth Engine.
- Se fornisci dati o algoritmi aggiuntivi, condividili solo se disponi dell'autorizzazione per farlo. Includi tutte le licenze e le attribuzioni richieste.
- Testa il codice.
- Assicurati di eseguire e testare tutti gli esempi di codice inclusi subito prima di inviare l'articolo per la revisione.
Intestazioni dei file del tutorial
Se crei e invii manualmente i tutorial della community senza utilizzare i modelli forniti in Scrittura di un tutorial, devi aggiungere manualmente i metadati e l'intestazione della licenza appropriati all'inizio del file. Seleziona il formato che preferisci per visualizzare un modello che può essere copiato nel tuo tutorial:
Markdown
Aggiungi quanto segue all'inizio del documento. L'intestazione non deve essere preceduta da spazi vuoti o altri caratteri:
---
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 template appropriati prima di inviare il tutorial per la revisione.
Colab
Aggiungi quanto segue a una cella di codice all'inizio del notebook:
#@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 riportato sopra può essere aperto direttamente nell'editor di file basato sul web di GitHub seguendo le istruzioni riportate in Scrittura di un tutorial.
Assicurati di consultare la pagina Scrivere un tutorial per informazioni importanti su come proporre, creare e inviare tutorial.
Colab
Per creare un nuovo notebook di Colab utilizzando il modello di stile consigliato, fai clic qui:
Si aprirà un notebook contenente le istruzioni per la creazione e l'invio del tutorial. Assicurati di consultare la pagina Scrittura di un tutorial per informazioni importanti sulla proposta, sulla creazione e sulla procedura di invio.