סקירה כללית
במדריך הזה אנחנו מספקים הנחיות כלליות לכתיבת מדריכים משלכם ל-Google Earth Engine. המטרה היא ליצור מדריכים איכותיים שיהיו ברורים, תמציתיים וקלים להבנה לכל חברי קהילת Earth Engine.
תבניות המדריכים שבהמשך יכולות לשמש גם כמדריך נוסף שיעזור לכם ליצור מדריכים משלכם. הוראות לשימוש בתבניות זמינות במאמר כתיבת מדריך.
בנוסף, מדריך הסגנון של Google Cloud Platform Community הוא מקור מידע חשוב לכתיבת מדריכים מקיפים לקהל רחב, ומדריך הסגנון של Google JavaScript מפרט את הסגנון המומלץ לשימוש בדוגמאות קוד של JavaScript. יכול להיות שהבודקים יסתמכו על המדריכים האלה במהלך הבדיקה של הבקשה שלכם.
הנחיות כלליות
- התנסחו בקצרה.
- אל תחזרו על עצמכם.
- אל תגידו את אותו הדבר פעמיים (גם אם אתם משתמשים בניסוח שונה).
- כדאי לסמן את ההתקדמות מדי פעם.
- כדאי לכלול תמונות וטקסט בנקודות חשובות במדריך כדי שהמשתמש ידע שהוא בדרך הנכונה. חשוב להשתמש בזה במידה!
- השתמשו בניסוח פעיל כשהדבר אפשרי.
- 'When the user changes the value' (כשהמשתמש משנה את הערך), ולא 'when the value is changed' (כשהערך משתנה).
- יוצא מן הכלל: מותר להשתמש בסביל אם צריך להתאמץ כדי להשתמש בפעיל, או אם ברור מי מבצע את הפעולה או אם זה לא רלוונטי (למשל, "מוחזר GIF מונפש" במקום "Earth Engine מחזיר GIF מונפש").
- צריך להתמקד בעובדות.
- כדאי להימנע משימוש בדרגת השוואה עליונה (סופרלטיב) ("זו השיטה הכי טובה ומהירה ב-100%").
- אל תקדמו מוצרים או שירותים.
- אל תעסקו בנושאים שנויים במחלוקת.
- כשמפנים לשיטות, למערכי נתונים ולניתוחים ספציפיים, צריך לכלול ציטוטים וכתובות URL.
- חשוב לוודא שההדרכה שלכם עומדת בפני עצמה.
- מומלץ לא להסתמך על ספריות מיוחדות מחוץ ל-API או על מערכי נתונים שלא נמצאים בקטלוג הנתונים הציבורי של Earth Engine.
- אם אתם מספקים נתונים או אלגוריתמים נוספים, אתם יכולים לשתף אותם רק אם יש לכם הרשאה לעשות זאת. עליכם לכלול את כל הרישיונות וההפניות הנדרשים.
- בודקים את הקוד.
- חשוב להריץ ולבדוק את כל דוגמאות הקוד שכלולות במאמר ממש לפני ששולחים אותו לבדיקה.
כותרות של קבצים במדריך
אם אתם יוצרים ושולחים הדרכות לקהילה באופן ידני בלי להשתמש בתבניות שמופיעות במאמר כתיבת הדרכה, תצטרכו להוסיף באופן ידני את המטא-נתונים המתאימים ואת כותרת הרישיון לתחילת הקובץ. בוחרים את הפורמט הרצוי כדי לראות תבנית שאפשר להעתיק למדריך משלכם:
Markdown
מוסיפים את הטקסט הבא לתחילת המסמך. אסור שיהיו רווחים או תווים אחרים לפני הכותרת:
---
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.
תבניות של הדרכות
Markdown
אם אתם מכירים את 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
כדי ליצור notebook חדש של Colab באמצעות תבנית הסגנון המומלצת, לוחצים כאן:
ייפתח מחברת עם הוראות ליצירה ולשליחה של המדריך. חשוב לעיין במאמר כתיבת הדרכה כדי לקבל פרטים חשובים על תהליך ההצעה, הכתיבה והשליחה.