Guia de estilo de tutoriais da comunidade

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 fáceis de entender para 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. Os detalhes sobre como usar os modelos para começar estão em Como escrever um tutorial.

Além disso, o Guia de estilo de tutoriais da comunidade do Google Cloud Platform oferece uma referência valiosa para escrever tutoriais completos para um público amplo, enquanto o Guia de estilo de JavaScript do Google 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 seja de forma diferente.
  • 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: é possível usar a voz passiva quando você tiver que se esforçar para usar a voz ativa ou se o ator 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 é o método 100% melhor e mais rápido").
    • Evite promover produtos ou serviços.
    • Evite temas controversos.
    • Inclua citações e URLs ao fazer referência a métodos, conjuntos de dados e análises específicos.
  • Deixe seu tutorial independente.
    • Tente não usar bibliotecas especiais fora da API ou conjuntos de dados que não estejam no catálogo público de dados 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 seu código.
    • Execute e teste todos os exemplos de código incluídos antes de enviar o artigo para revisão.

Cabeçalhos de arquivo de tutorial

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 o cabeçalho de metadados e licença apropriado ao início do arquivo. Selecione o formato desejado para conferir 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ê estiver familiarizado com o Git e o GitHub, use o código abaixo como um 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 conferir detalhes importantes sobre como propor, criar e enviar tutoriais.

Colab

Para criar um novo bloco do Colab usando o modelo de estilo recomendado, clique aqui:

Novo tutorial do Colab

Isso vai abrir um notebook com instruções para criar e enviar seu tutorial. Consulte Como escrever um tutorial para conferir detalhes importantes sobre a proposta, a criação e o processo de envio.