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 muestran a continuación también sirven como guía adicional para ayudarte a comenzar tus propios instructivos. En Cómo escribir un instructivo, puedes encontrar detalles para comenzar a usar las plantillas.
Además, la Guía de estilo de los instructivos de la comunidad de Google Cloud 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. Los revisores pueden consultar 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 puntos clave del instructivo para que el usuario sepa que va por buen camino. Ú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: Se puede usar la voz pasiva cuando tendrías que esforzarte para usar la voz activa o si el actor es obvio o no es relevante ("se devuelve un GIF animado" en lugar de "Earth Engine devuelve un GIF animado").
- Enfóquense en los hechos.
- Evita los superlativos ("este es 100% el mejor y más rápido método").
- Evita promocionar productos o servicios.
- Evita los temas polémicos.
- Incluye citas y URLs cuando hagas referencia a métodos, conjuntos de datos y análisis específicos.
- Haz que tu instructivo sea autónomo.
- Intenta no depender de bibliotecas especiales fuera de la API ni de conjuntos de datos que no estén en el catálogo de datos público de Earth Engine.
- Si proporcionas datos o algoritmos adicionales, compártelos solo 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 proporcionadas en Escribe un instructivo, deberás agregar de forma manual los metadatos y el encabezado de licencia adecuados al comienzo del archivo. Selecciona el formato que desees para ver una plantilla que se pueda copiar en tu propio instructivo:
Markdown
Agrega lo siguiente al principio 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 adecuados antes de enviar el instructivo 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, la plantilla anterior se puede abrir 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, crear y enviar instructivos.
Colab
Para crear un notebook de Colab nuevo con la plantilla de estilo 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 la propuesta, la creación y el proceso de envío.