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. Ma on ułatwić tworzenie 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 rozpocząć tworzenie własnych samouczków. Szczegółowe informacje o tym, jak zacząć korzystać z szablonów, znajdziesz w artykule Pisanie samouczka.

Ponadto Przewodnik po stylu samouczków społeczności Google Cloud zawiera cenne wskazówki dotyczące pisania kompleksowych samouczków dla szerokiego grona odbiorców, a Przewodnik po stylu Google JavaScript szczegółowo opisuje zalecany styl do stosowania w przykładowych kodach JavaScript. Weryfikatorzy mogą korzystać z tych przewodników podczas sprawdzania Twojego zgłoszenia.

Ogólne wskazówki

  • Zadbaj o zwięzłość.
  • Nie powtarzaj się.
    • Nie powtarzaj tych samych informacji (nawet jeśli są sformułowane inaczej).
  • Okresowo oznaczaj postępy.
    • W kluczowych punktach samouczka umieść obrazy i tekst, aby użytkownik wiedział, że jest na właściwej drodze. 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 nienaturalnego sformułowania lub jeśli wykonawca jest oczywisty lub nieistotny („zwracany jest animowany GIF” zamiast „Earth Engine zwraca animowany GIF”).
  • Trzymaj się faktów.
    • Unikaj stosowania stopnia najwyższego („to w 100% najlepsza i najszybsza metoda”).
    • Nie promuj produktów ani usług.
    • Unikaj kontrowersyjnych tematów.
    • Podczas odwoływania się do konkretnych metod, zbiorów danych i analiz podawaj cytaty i adresy URL.
  • Samouczek powinien być samodzielny.
    • Staraj się nie polegać na specjalnych bibliotekach spoza interfejsu API ani na zbiorach danych, które nie znajdują się w publicznym Earth Engine Data Catalog.
    • Jeśli udostępniasz dodatkowe dane lub algorytmy, rób to tylko wtedy, gdy masz na to zgodę. Dołącz wszystkie wymagane licencje i informacje o autorach.
  • Przetestuj kod.
    • Przed przesłaniem artykułu do sprawdzenia uruchom i przetestuj wszystkie zawarte w nim przykładowe kody.

Nagłówki plików samouczka

Jeśli tworzysz i przesyłasz samouczki społeczności ręcznie bez używania szablonów podanych w artykule Pisanie 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 mogą znajdować się odstępy ani inne znaki:

---
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 zastąp odpowiednie pola szablonu.

Colab

Dodaj ten kod do komórki z kodem na początku notatnika:

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

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

Możesz też otworzyć powyższy szablon bezpośrednio w internetowym edytorze plików GitHuba, postępując zgodnie z instrukcjami podanymi w artykule Pisanie samouczka.

Zapoznaj się z artykułem Pisanie samouczka, aby dowiedzieć się, jak proponować, tworzyć i przesyłać samouczki.

Colab

Aby utworzyć nowy notatnik Colab przy użyciu zalecanego szablonu stylu, kliknij tutaj:

Nowy samouczek Colab

Otworzy się notatnik zawierający instrukcje tworzenia i przesyłania samouczka. Zapoznaj się z artykułem Pisanie samouczka, aby uzyskać ważne informacje na temat procesu tworzenia i przesyłania propozycji oraz samouczka.