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 về Google Earth Engine của riêng bạn. Mục đích của chương trình này là giúp bạn dễ dàng tạo các bài hướng dẫn chất lượng cao, rõ ràng, súc tích và dễ hiểu cho toàn bộ cộng đồng Earth Engine.

Mẫu hướng dẫn bên dưới cũng đóng vai trò là 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 cung cấp một tài liệu tham khảo hữu ích để viết hướng dẫn toàn diện cho nhiều đối tượng, còn Hướng dẫn về phong cách viết JavaScript của Google trình bày chi tiết phong cách nên dùng trong các mã mẫu JavaScript. Nhân viên đánh giá có thể tham khảo các hướng dẫn này khi xem xét nội dung bạn gửi.

Nguyên tắc chung

  • Ngắn gọn.
  • Đừng lặp lại.
    • Đừng nói cùng một điều hai lần (ngay cả khi dùng từ khác nhau).
  • Đánh dấu tiến trình định kỳ.
    • Thêm hình ảnh và văn bản tại các điểm chính trong hướng dẫn để người dùng biết họ đang đi đúng hướng. Sử dụng một cách tiết kiệm!
  • Sử dụng thể 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ị thay đổi".
    • Ngoại lệ: Bạn có thể sử dụng thể bị động khi phải cố gắng lắm mới dùng được thể chủ động, hoặc nếu chủ thể đã rõ ràng hoặc không liên quan ("ảnh GIF động được trả về" thay vì "Earth Engine trả về ảnh GIF động").
  • Chỉ đưa ra thông tin thực tế.
    • Tránh dùng từ ngữ mang tính cường điệu ("đâ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 cá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, chỉ chia sẻ chúng nếu bạn có quyền làm như vậy. Hãy thêm tất cả giấy phép và thông tin ghi nhận tác giả bắt buộc.
  • Kiểm thử mã.
    • Hãy nhớ chạy và kiểm thử tất cả mã mẫu có trong bài viết ngay trước khi gửi bài viết để xem xét.

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

Nếu bạn đang tạo và gửi hướng dẫn cộng đồng theo cách thủ công mà không sử dụng các mẫu được cung cấp trong phần Viết hướng dẫn, bạn sẽ 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ẫu mà bạn có thể sao chép vào hướng dẫn của riêng mình:

Markdown

Thêm nội dung sau vào đầu tài liệu. Không được có khoảng trắng hoặc ký tự nào 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 để xem xét.

Colab

Thêm đoạn mã sau vào một ô mã ở đầu sổ ghi chú:

#@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ã dưới đây 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 trong phần 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, soạn thảo 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ổ ghi chú có hướng dẫn về cách biên soạn và gửi hướng dẫn của bạ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.