Обзор
В этом руководстве приведены общие рекомендации по написанию собственных руководств по Google Earth Engine. Цель – упростить создание качественных руководств, которые будут понятны и полезны всему сообществу Earth Engine.
Шаблоны руководств ниже также могут служить дополнительным руководством, которое поможет вам начать работу над собственными руководствами. Подробные инструкции по использованию шаблонов можно найти в статье Как написать руководство.
Кроме того, Руководство по стилю для руководств сообщества Google Cloud содержит ценные рекомендации по написанию руководств для широкой аудитории, а Руководство по стилю Google JavaScript подробно описывает рекомендуемый стиль для использования в примерах кода JavaScript. Специалисты могут обращаться к этим руководствам при проверке вашего приложения.
Общие рекомендации
- Будьте кратки.
- Не повторяйтесь.
- Не повторяйте одну и ту же мысль дважды, даже если вы используете разные слова.
- Периодически отмечайте прогресс.
- Добавьте изображения и текст в ключевые моменты руководства, чтобы пользователь знал, что он на правильном пути. Не используйте эту категорию слишком часто.
- По возможности используйте действительный залог.
- "Когда пользователь меняет значение", а не "когда значение меняется".
- Исключение: пассивный залог можно использовать, если активный залог неуместен или если действующее лицо очевидно или не имеет значения ("возвращается анимированный GIF" вместо "Earth Engine возвращает анимированный GIF").
- Придерживайтесь фактов.
- Избегайте превосходных степеней ("это на 100% лучший и самый быстрый способ").
- Не рекламируйте товары или услуги.
- Избегайте спорных тем.
- Включайте цитаты и URL-адреса при ссылке на конкретные методы, наборы данных и анализы.
- Сделайте видео самодостаточным.
- Старайтесь не полагаться на специальные библиотеки за пределами API или наборы данных, которых нет в общедоступном каталоге данных Earth Engine.
- Если вы предоставляете дополнительные данные или алгоритмы, делитесь ими только в том случае, если у вас есть на это разрешение. Укажите все необходимые лицензии и атрибуции.
- Протестируйте код.
- Перед отправкой статьи на проверку обязательно запустите и протестируйте все включенные в нее примеры кода.
Заголовки файлов руководства
Если вы создаете и отправляете руководства вручную, не используя шаблоны, приведенные в разделе Написание руководства, вам нужно будет вручную добавить соответствующие метаданные и заголовок лицензии в начало файла. Выберите нужный формат, чтобы посмотреть шаблон, который можно скопировать в ваше руководство.
Разметка Markdown
Добавьте в начало документа следующий код: Перед заголовком не должно быть пробелов или других символов:
---
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.
-->
Перед отправкой руководства на проверку не забудьте заменить соответствующие поля шаблона.
Colab
Добавьте в ячейку кода в начале блокнота следующее:
#@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.
Обучающие видео
Разметка Markdown
Если вы знакомы с git и GitHub, то можете использовать приведенный ниже код в качестве шаблона.
---
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.
Вы также можете открыть шаблон в веб-редакторе GitHub, следуя инструкциям в статье Как написать руководство.
Обязательно ознакомьтесь с руководством по написанию руководств, чтобы узнать, как предлагать, создавать и отправлять руководства.
Colab
Чтобы создать блокнот Colab на основе рекомендуемого шаблона, нажмите на ссылку ниже.
Откроется блокнот с инструкциями по созданию и отправке руководства. Обязательно ознакомьтесь с руководством по написанию учебных пособий, в котором содержится важная информация о предложении, создании и отправке учебных пособий.