סקירה כללית
במדריך הזה מפורטות הנחיות כלליות לכתיבת מדריכים משלכם ל-Google Earth Engine. המטרה שלו היא לאפשר יצירה קלה של מדריכים איכותיים, ברורים, תמציתיים וקלים להבנה לכל קהילת Earth Engine.
התבניות של המדריכים שבהמשך יכולות לשמש גם כמדריך נוסף שיעזור לכם להתחיל ליצור מדריכים משלכם. במאמר כתיבת מדריך מוסבר איך להשתמש בתבניות כדי להתחיל.
בנוסף, מדריך הסגנון של Google Cloud Community Tutorial מספק חומר עזר חשוב לכתיבת מדריכים מקצה לקצה לקהל רחב, ומדריך הסגנון של Google JavaScript מפרט את הסגנון המומלץ לשימוש בדוגמאות קוד של JavaScript. יכול להיות שהבודקים יעיינו במדריכים האלה כשהם יבדקו את הבקשה שלכם.
הנחיות כלליות
- תהיו תמציתיים.
- אל תחזרו על עצמכם.
- אל תגידו את אותו הדבר פעמיים (גם אם הניסוח שונה).
- לסמן את ההתקדמות מדי פעם.
- כדאי לכלול תמונות וטקסט בנקודות מפתח במדריך כדי שהמשתמשים ידעו שהם בכיוון הנכון. השתמשו בהם במידה!
- השתמשו בניסוח פעיל כשאפשר.
- "כשהמשתמש משנה את הערך", ולא "כשהערך משתנה".
- חריג: אפשר להשתמש בלשון סביל אם צריך להתאמץ כדי להשתמש בלשון פעיל, או אם הפועל ברור או לא רלוונטי ("מוחזר קובץ 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
מוסיפים את הקוד הבא לתא קוד בתחילת ה-notebook:
#@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 באמצעות תבנית הסגנון המומלצת, לוחצים כאן:
הפעולה הזו תפתח תיקיית Notebook עם הוראות ליצירה ולשליחה של המדריך. חשוב לעיין במאמר כתיבת מדריך כדי לקבל פרטים חשובים על תהליך ההצעה, הכתיבה והשליחה.