Descripción general
En esta guía, se proporcionan lineamientos generales para escribir tus propios instructivos de Google Earth Engine. Su objetivo es facilitar la creación de instructivos de alta calidad que sean claros, concisos y fáciles de entender para toda la comunidad de Earth Engine.
Las plantillas de instructivos que se incluyen a continuación también sirven como guía adicional para ayudarte a comenzar tus propios instructivos. En Cómo escribir un instructivo, encontrarás detalles sobre cómo usar las plantillas para comenzar.
Además, la Guía de estilo de los instructivos de la comunidad de Google Cloud Platform proporciona una referencia valiosa para escribir instructivos de extremo a extremo para un público amplio, mientras que la Guía de estilo de JavaScript de Google detalla el estilo recomendado para usar en las muestras de código de JavaScript. Es posible que los revisores consulten estas guías cuando revisen tu envío.
Lineamientos generales
- Sea breve.
- No te repitas.
- No digas lo mismo dos veces (incluso si lo expresas de manera diferente).
- Marca el progreso periódicamente.
- Incluye imágenes y texto en los puntos clave del instructivo para que el usuario sepa que está en el camino correcto. ¡Úsala con moderación!
- Usa la voz activa siempre que sea posible.
- "Cuando el usuario cambia el valor", no "cuando se cambia el valor".
- Excepción: Está bien usar la voz pasiva cuando tengas que esforzarte para usar la voz activa o si el actor es obvio o no es relevante ("se muestra un GIF animado" en lugar de "Earth Engine muestra un GIF animado").
- Limítate a los hechos.
- Evita los superlativos ("este es el método mejor y más rápido").
- Evita promocionar productos o servicios.
- Evita los temas controversiales.
- Incluye citas y URLs cuando hagas referencia a métodos, conjuntos de datos y análisis específicos.
- Haz que el instructivo sea autónomo.
- Intenta no depender de bibliotecas especiales fuera de la API o de conjuntos de datos que no estén en el catálogo de datos públicos de Earth Engine.
- Si proporcionas datos o algoritmos adicionales, solo compártelos si tienes permiso para hacerlo. Incluye todas las licencias y atribuciones requeridas.
- Prueba el código.
- Asegúrate de ejecutar y probar todas las muestras de código incluidas justo antes de enviar tu artículo para su revisión.
Encabezados de archivos de instructivos
Si creas y envías instructivos de la comunidad de forma manual sin usar las plantillas que se proporcionan en Cómo escribir un instructivo, deberás agregar de forma manual los metadatos y el encabezado de licencia adecuados al comienzo del archivo. Selecciona el formato deseado para ver una plantilla que se puede copiar en tu propio instructivo:
Markdown
Agrega lo siguiente al comienzo del documento. No debe haber espacios en blanco ni otros caracteres antes del encabezado:
---
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.
-->
Asegúrate de reemplazar los campos de plantilla correspondientes antes de enviar tu tutorial para su revisión.
Colab
Agrega lo siguiente a una celda de código al principio 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.
Plantillas de instructivos
Markdown
Si conoces git y GitHub, puedes usar el siguiente código como plantilla para comenzar:
---
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, puedes abrir la plantilla anterior directamente en el editor de archivos basado en la Web de GitHub siguiendo las instrucciones que se indican en Cómo escribir un instructivo.
Asegúrate de consultar Cómo escribir un instructivo para obtener detalles importantes sobre cómo proponer, escribir y enviar instructivos.
Colab
Para crear un nuevo notebook de Colab con la plantilla de diseño recomendada, haz clic aquí:
Se abrirá un notebook con instrucciones para crear y enviar tu instructivo. Asegúrate de consultar Cómo escribir un instructivo para obtener detalles importantes sobre el proceso de propuesta, creación y envío.