Hướng dẫn về kiểu cho video hướng dẫn dành cho cộng đồng

Tổng quan

Hướng dẫn này cung cấp các nguyên tắc chung để viết hướng dẫn của riêng bạn về Google Earth Engine. Mục tiêu của dự án này là giúp bạn dễ dàng tạo các hướng dẫn chất lượng cao, rõ ràng, ngắn gọn và dễ hiểu cho toàn bộ cộng đồng Earth Engine.

Các mẫu hướng dẫn bên dưới cũng là một hướng dẫn bổ sung giúp bạn bắt đầu tạo hướng dẫn của riêng mình. Bạn có thể xem thông tin chi tiết về cách sử dụng các mẫu để bắt đầu trong phần Viết hướng dẫn.

Ngoài ra, Hướng dẫn về phong cách viết hướng dẫn cho cộng đồng Google Cloud Platform cung cấp một tài liệu tham khảo có giá trị để viết hướng dẫn từ đầu đến cuối cho nhiều đối tượng, trong khi Hướng dẫn về phong cách viết JavaScript của Google trình bày chi tiết phong cách được đề xuất để sử dụng trong các mẫu mã JavaScript. Nhân viên đánh giá có thể tham khảo những hướng dẫn này khi xem xét nội dung bạn gửi.

Nguyên tắc chung

  • Trình bày ngắn gọn.
  • Đừng lặp lại.
    • Đừng nói cùng một điều hai lần (ngay cả khi bạn diễn đạt khác đi).
  • Đánh dấu tiến trình theo định kỳ.
    • Đưa hình ảnh và văn bản vào các điểm chính trong hướng dẫn để người dùng biết họ đang đi đúng hướng. Hãy sử dụng một cách tiết kiệm!
  • Sử dụng câu chủ động bất cứ khi nào có thể.
    • "Khi người dùng thay đổi giá trị", chứ không phải "khi giá trị được thay đổi".
    • Trường hợp ngoại lệ: Bạn có thể dùng thể bị động khi phải cố gắng dùng thể chủ động, hoặc nếu chủ thể rõ ràng hoặc không liên quan ("một ảnh GIF động được trả về" thay vì "Earth Engine trả về một ảnh GIF động").
  • Chỉ lấy thông tin thực tế.
    • Tránh dùng các từ ngữ ở dạng so sánh nhất ("đây là phương pháp tốt nhất và nhanh nhất 100%").
    • Tránh quảng bá sản phẩm hoặc dịch vụ.
    • Tránh các chủ đề gây tranh cãi.
    • Thêm trích dẫn và URL khi tham chiếu đến các phương pháp, tập dữ liệu và phân tích cụ thể.
  • Tạo hướng dẫn độc lập.
    • Cố gắng không dựa vào các thư viện đặc biệt bên ngoài API hoặc tập dữ liệu không có trong Danh mục dữ liệu công khai của Earth Engine.
    • Nếu bạn cung cấp thêm dữ liệu hoặc thuật toán, hãy chỉ chia sẻ chúng nếu bạn có quyền làm như vậy. Hãy thêm tất cả các giấy phép và thông tin ghi nhận bắt buộc.
  • Kiểm thử mã của bạn.
    • Hãy nhớ chạy và kiểm thử tất cả các mẫu mã được đưa vào ngay trước khi gửi bài viết của bạn đi xem xét.

Tiêu đề tệp hướng dẫn

Nếu đang tạo và gửi hướng dẫn cho cộng đồng theo cách thủ công mà không sử dụng các mẫu có trong phần Viết hướng dẫn, bạn cần thêm siêu dữ liệu và tiêu đề giấy phép thích hợp vào đầu tệp theo cách thủ công. Chọn định dạng mong muốn để xem một mẫu có thể sao chép vào hướng dẫn của riêng bạn:

Markdown

Thêm nội dung sau vào đầu tài liệu. Không được có khoảng trắng hoặc các ký tự khác trước tiêu đề:

---
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.
-->

Hãy nhớ thay thế các trường mẫu thích hợp trước khi gửi hướng dẫn của bạn để chúng tôi xem xét.

Colab

Thêm nội dung sau vào một ô mã ở đầu sổ tay:

#@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.

Mẫu hướng dẫn

Markdown

Nếu quen thuộc với git và GitHub, bạn có thể sử dụng mã bên dưới làm mẫu để bắt đầu:

---
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.

Ngoài ra, bạn có thể mở trực tiếp mẫu trên trong trình chỉnh sửa tệp dựa trên web của GitHub bằng cách làm theo hướng dẫn tại Viết hướng dẫn.

Hãy nhớ tham khảo bài viết Viết hướng dẫn để biết thông tin quan trọng về cách đề xuất, viết và gửi hướng dẫn.

Colab

Để tạo một sổ tay Colab mới bằng mẫu kiểu được đề xuất, hãy nhấp vào đây:

Hướng dẫn mới về Colab

Thao tác này sẽ mở một sổ tay có hướng dẫn về cách tạo và gửi hướng dẫn. Hãy nhớ tham khảo bài viết Viết hướng dẫn để biết thông tin quan trọng về quy trình đề xuất, biên soạn và gửi bài viết.