コミュニティ チュートリアルのスタイルガイド

概要

このガイドでは、独自の Google Earth Engine チュートリアルを作成するための一般的なガイドラインについて説明します。このガイドは、Earth Engine コミュニティ全体にとって明確で簡潔、かつ理解しやすい高品質なチュートリアルを簡単に作成できるようにすることを目的としています。

以下のチュートリアル テンプレートは、独自のチュートリアルを開始するための追加ガイドとしても機能します。テンプレートを使用して開始する方法の詳細については、チュートリアルの作成をご覧ください。

また、Google Cloud コミュニティ チュートリアル スタイルガイドは、幅広い対象者向けのエンドツーエンドのチュートリアルを作成する際に役立つリファレンスです。Google JavaScript スタイルガイドには、JavaScript コードサンプルで使用する推奨スタイルが詳しく記載されています。審査担当者は、提出されたアプリを審査する際に、これらのガイドを参照することがあります。

一般的なガイドライン

  • 簡潔にする。
  • 同じことを繰り返さない。
    • 同じことを 2 回言わない（表現を変えても同じ）。
  • 定期的に進捗状況を記録します。
    • チュートリアルの重要なポイントに画像とテキストを挿入して、ユーザーが正しい手順を踏んでいることを確認できるようにします。使いすぎないようにしてください。
  • 可能な限り能動態を使用します。
    • 「値が変更されたとき」ではなく、「ユーザーが値を変更したとき」です。
    • 例外: 能動態を使用するために無理をする必要がある場合や、行為者が明白であるか関連性がない場合は、受動態を使用してもかまいません（「Earth Engine は GIF アニメーションを返します」ではなく「GIF アニメーションが返されます」）。
  • 事実を最重視して、
    • 過剰な表現（「これは 100% 最善かつ最速の方法です」など）は避けてください。
    • 商品やサービスの宣伝は避けてください。
    • 物議を醸すようなトピックは避けてください。
    • 特定のメソッド、データセット、分析を参照する場合は、引用と URL を含めます。
  • チュートリアルを自己完結型にします。
    • API 以外の特別なライブラリや、公開されている Earth Engine Data Catalog にないデータセットに依存しないようにしてください。
    • 追加のデータやアルゴリズムを提供する場合は、提供する権限がある場合にのみ共有してください。必要なライセンスと帰属表示をすべて含めてください。
  • コードをテストします。
    • 記事を審査のために送信する直前に、含まれているすべてのコードサンプルを実行してテストしてください。

チュートリアル ファイルのヘッダー

チュートリアルの作成で提供されているテンプレートを使用せずに、コミュニティ チュートリアルを手動で作成して送信する場合は、適切なメタデータとライセンス ヘッダーをファイルの先頭に手動で追加する必要があります。目的の形式を選択して、独自のチュートリアルにコピーできるテンプレートを表示します。

マークダウン

ドキュメントの先頭に以下を追加します。ヘッダーの前に空白文字やその他の文字を配置しないでください。

---
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 ノートブックを作成するには、こちらをクリックしてください。

新しい Colab チュートリアル

これにより、チュートリアルの作成と送信の手順が記載されたノートブックが開きます。提案、作成、送信プロセスの重要な詳細については、チュートリアルの作成をご覧ください。