Poradnik stylistyczny dotyczący samouczków społeczności

Przegląd

Ten przewodnik zawiera ogólne wskazówki dotyczące pisania własnych samouczków Google Earth Engine. Jego celem jest ułatwienie tworzenia wysokiej jakości samouczków, które są jasne, zwięzłe i łatwe do zrozumienia dla całej społeczności Earth Engine.

Poniższe szablony samouczków mogą też służyć jako dodatkowy przewodnik, który pomoże Ci zacząć tworzyć własne samouczki. Szczegółowe informacje o tym, jak korzystać z szablonów, znajdziesz w artykule Pisanie samouczka.

Dodatkowo przewodnik po stylu samouczków społeczności Google Cloud Platform zawiera cenne wskazówki dotyczące pisania kompleksowych samouczków dla szerokiego grona odbiorców, a przewodnik po stylu JavaScript Google zawiera szczegółowe informacje o zalecanym stylu, który należy stosować w przykładowych kodach JavaScript. Weryfikatorzy mogą korzystać z tych przewodników podczas sprawdzania przesłanych przez Ciebie materiałów.

Ogólne wskazówki

  • Pisz zwięźle.
  • Nie powtarzaj się.
    • Nie powtarzaj tego samego (nawet jeśli używasz innych słów).
  • Okresowo oznaczaj postępy.
    • W kluczowych momentach samouczka umieszczaj obrazy i tekst, aby użytkownik wiedział, że wszystko idzie zgodnie z planem. Używaj oszczędnie.
  • W miarę możliwości używaj strony czynnej.
    • „Gdy użytkownik zmieni wartość”, a nie „gdy wartość zostanie zmieniona”.
    • Wyjątek: możesz używać strony biernej, jeśli użycie strony czynnej wymagałoby zbyt dużego wysiłku lub jeśli wykonawca jest oczywisty lub nieistotny („zwracany jest animowany GIF” zamiast „Earth Engine zwraca animowany GIF”).
  • Trzymaj się faktów.
    • Unikaj superlatywów („to jest w 100% najlepsza i najszybsza metoda”).
    • nie promuj produktów ani usług;
    • Unikaj kontrowersyjnych tematów.
    • Podawaj cytaty i adresy URL, gdy odwołujesz się do konkretnych metod, zbiorów danych i analiz.
  • Spraw, aby Twój samouczek był niezależny.
    • Staraj się nie korzystać ze specjalnych bibliotek spoza interfejsu API ani zbiorów danych, które nie znajdują się w publicznym katalogu danych Earth Engine.
    • Jeśli udostępniasz dodatkowe dane lub algorytmy, rób to tylko wtedy, gdy masz na to pozwolenie. Dołącz wszystkie wymagane licencje i informacje o autorstwie.
  • Przetestuj kod.
    • Przed przesłaniem artykułu do sprawdzenia uruchom i przetestuj wszystkie przykłady kodu.

Nagłówki plików samouczka

Jeśli tworzysz i przesyłasz samouczki dla społeczności ręcznie, bez korzystania z szablonów podanych w artykule Tworzenie samouczka, musisz ręcznie dodać odpowiednie metadane i nagłówek licencji na początku pliku. Wybierz odpowiedni format, aby wyświetlić szablon, który możesz skopiować do własnego samouczka:

Markdown

Dodaj na początku dokumentu te informacje: Przed nagłówkiem nie może być żadnych spacji ani innych znaków:

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

Przed przesłaniem samouczka do sprawdzenia pamiętaj, aby zastąpić odpowiednie pola szablonu.

Colab

Na początku notatnika dodaj do komórki z kodem ten fragment:

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

Szablony samouczków

Markdown

Jeśli znasz git i GitHub, możesz użyć poniższego kodu jako szablonu, aby zacząć:

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

Powyższy szablon można też otworzyć bezpośrednio w internetowym edytorze plików GitHub, postępując zgodnie z instrukcjami w artykule Writing a Tutorial (pisanie samouczka).

Więcej informacji o tym, jak proponować, tworzyć i przesyłać samouczki, znajdziesz w artykule Tworzenie samouczka.

Colab

Aby utworzyć nowy notatnik Colab za pomocą polecanego szablonu stylu, kliknij tutaj:

Nowy samouczek Colab

Otworzy się notatnik z instrukcjami tworzenia i przesyłania samouczka. Więcej informacji o proponowaniu, tworzeniu i przesyłaniu samouczków znajdziesz w artykule Tworzenie samouczka.