Visão geral
Este guia fornece diretrizes gerais para escrever seus próprios tutoriais do Google Earth Engine. O objetivo é facilitar a criação de tutoriais de alta qualidade que sejam claros, concisos e facilmente compreendidos por toda a comunidade do Earth Engine.
Os modelos de tutorial abaixo também servem como um guia adicional para ajudar você a começar seus próprios tutoriais. Para saber como usar os modelos para começar, consulte Como escrever um tutorial.
Além disso, o Guia de estilo de tutoriais da comunidade do Google Cloud é uma referência valiosa para escrever tutoriais completos para um público amplo, enquanto o Guia de estilo do Google para JavaScript detalha o estilo recomendado para uso em exemplos de código JavaScript. Os revisores podem consultar esses guias ao analisar seu envio.
Diretrizes gerais
- Seja breve.
- Não se repita.
- Não diga a mesma coisa duas vezes (mesmo que com palavras diferentes).
- Marque o progresso periodicamente.
- Inclua imagens e texto em pontos importantes do tutorial para que o usuário saiba que está no caminho certo. Use com moderação.
- Use a voz ativa sempre que possível.
- "Quando o usuário muda o valor", não "quando o valor é mudado".
- Exceção: é aceitável usar a voz passiva quando for difícil usar a voz ativa ou se o agente for óbvio ou irrelevante ("um GIF animado é retornado" em vez de "o Earth Engine retorna um GIF animado").
- Atenha-se aos fatos.
- Evite superlativos ("este é 100% o melhor e mais rápido método").
- Evite promover produtos ou serviços.
- Evite temas polêmicos.
- Inclua citações e URLs ao fazer referência a métodos, conjuntos de dados e análises específicos.
- Crie um tutorial independente.
- Tente não depender de bibliotecas especiais fora da API ou de conjuntos de dados que não estejam no Catálogo de dados público do Earth Engine.
- Se você estiver fornecendo dados ou algoritmos adicionais, compartilhe-os apenas se tiver permissão para isso. Inclua todas as licenças e atribuições necessárias.
- Teste o código.
- Execute e teste todos os exemplos de código incluídos antes de enviar o artigo para revisão.
Cabeçalhos de arquivos de tutoriais
Se você estiver criando e enviando tutoriais da comunidade manualmente sem usar os modelos fornecidos em Como escrever um tutorial, será necessário adicionar manualmente os metadados e o cabeçalho de licença apropriados ao início do arquivo. Selecione o formato desejado para ver um modelo que pode ser copiado para seu próprio tutorial:
Markdown
Adicione o seguinte ao início do documento. Nenhum espaço em branco ou outro caractere deve preceder o cabeçalho:
---
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.
-->
Substitua os campos de modelo apropriados antes de enviar o tutorial para revisão.
Colab
Adicione o seguinte a uma célula de código no início do 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.
Modelos de tutorial
Markdown
Se você já conhece o git e o GitHub, use o código abaixo como modelo para começar:
---
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.
Como alternativa, o modelo acima pode ser aberto diretamente no editor de arquivos baseado na Web do GitHub seguindo as instruções em Como escrever um tutorial.
Consulte Como escrever um tutorial para ver detalhes importantes sobre como propor, criar e enviar tutoriais.
Colab
Para criar um notebook do Colab usando o modelo de estilo recomendado, clique aqui:
Isso vai abrir um notebook com instruções para criar e enviar o tutorial. Consulte Como escrever um tutorial para ver detalhes importantes sobre o processo de proposta, criação e envio.