Обзор
Это руководство содержит общие рекомендации по написанию собственных руководств по Google Earth Engine. Его цель — упростить создание высококачественных руководств, которые будут ясными, лаконичными и легко понятными для всего сообщества Earth Engine.
Представленные ниже шаблоны для обучающих материалов также служат дополнительным руководством, которое поможет вам начать создавать собственные обучающие материалы. Подробную информацию о том, как использовать шаблоны для начала работы, можно найти в разделе «Написание обучающего материала» .
Кроме того, руководство по стилю оформления учебных пособий сообщества Google Cloud Platform Community Style Guide является ценным справочником для написания комплексных руководств для широкой аудитории, а руководство по стилю JavaScript от Google подробно описывает рекомендуемый стиль для использования в примерах кода JavaScript. Рецензенты могут обращаться к этим руководствам при проверке вашей работы.
Общие рекомендации
- Будьте кратки.
- Не повторяйтесь.
- Не повторяйте одно и то же дважды (даже если формулировка отличается).
- Периодически отмечайте достигнутый прогресс.
- В ключевых моментах руководства добавляйте изображения и текст, чтобы пользователь понимал, что он на правильном пути. Используйте их умеренно!
- По возможности используйте активный залог.
- "Когда пользователь изменяет значение", а не "когда значение изменяется".
- Исключение: использование пассивного залога допустимо, если для использования активного залога пришлось бы приложить дополнительные усилия, или если субъект действия очевиден или не имеет отношения к делу («возвращается анимированный GIF» вместо «Earth Engine возвращает анимированный GIF»).
- Придерживайтесь фактов.
- Избегайте превосходных степеней («это на 100% лучший и самый быстрый метод»).
- Избегайте рекламы товаров или услуг.
- Избегайте спорных тем.
- При цитировании конкретных методов, наборов данных и анализов обязательно указывайте ссылки на источники и URL-адреса.
- Сделайте свой учебный материал самодостаточным.
- Старайтесь не полагаться на специальные библиотеки, находящиеся вне API, или на наборы данных, не включенные в общедоступный каталог данных Earth Engine .
- Если вы предоставляете дополнительные данные или алгоритмы, делитесь ими только с разрешения. Укажите все необходимые лицензии и ссылки на источники.
- Протестируйте свой код.
- Обязательно запустите и протестируйте все включенные примеры кода непосредственно перед отправкой статьи на рецензирование.
Заголовки файлов учебного пособия
Если вы создаете и отправляете руководства для сообщества вручную, не используя шаблоны, предоставленные в разделе «Написание руководства» , вам потребуется вручную добавить соответствующие метаданные и заголовок лицензии в начало файла. Выберите нужный формат, чтобы просмотреть шаблон, который можно скопировать в ваше собственное руководство:
Маркдаун
Добавьте в начало документа следующий текст. Перед заголовком не должно быть пробелов или других символов:
---
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.
Шаблоны для обучающих материалов
Маркдаун
Если вы знакомы с 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, используя рекомендуемый шаблон стиля, нажмите здесь:
Откроется блокнот с инструкциями по созданию и отправке вашего учебного пособия. Обязательно обратитесь к разделу «Написание учебного пособия» для получения важной информации о процессе подачи заявки, создания и отправки.