כתיבת מדריך ראשון לקהילה

המרחב הזה מיועד למשתמשי Earth Engine שרוצים לשתף את הידע שלהם עם שאר הקהילה של Earth Engine. המדריכים בקטע הזה נוצרו על ידי משתמשי Earth Engine, עבור משתמשי Earth Engine, והם מיועדים לכל הרמות, ממשתמשים מתחילים ועד למשתמשים מתקדמים יותר.

אפשר לשלוח מדריכים כטקסט פשוט וקוד שעוצב באמצעות שפת הסימון Markdown, או כ-notebook של Colab שמכיל Markdown וקוד Python שניתן להפעלה. הדרכות שנבנו באמצעות ספריות הלקוח של Earth Engine JavaScript נכתבות בדרך כלל ב-Markdown, ואילו Colab מומלץ להדרכות שמבוססות על ספריות הלקוח של Earth Engine Python.

לפני שמתחילים

קוד ההתנהגות

צוות Earth Engine מחויב לטפח קהילה מכילה שבה אין מקום להטרדות. לפני ששולחים תרומה, חשוב לקרוא בעיון את קוד ההתנהגות שלנו.

הצטרפות ל-GitHub

הדרכות של קהילת Earth Engine משותפות ונבדקות דרך GitHub. אם עדיין אין לכם חשבון GitHub, אתם צריכים ליצור חשבון בכתובת https://github.com/join.

הצעת מדריך

לפני שמשקיעים זמן ומאמץ משמעותיים ביצירת הדרכה חדשה, אנחנו מבקשים מהתורמים הפוטנציאליים לשלוח הצעה פשוטה עם מידע בסיסי. כך המחברים יכולים לעבוד עם האחראים על תחזוקת מסמכי התיעוד למפתחים של Earth Engine, ולהתמקד ביצירת מדריכים שמספקים את הערך הרב ביותר לקהילת המשתמשים של Earth Engine. בנוסף, היא חוסכת זמן כי היא מונעת מצב שבו נצטרך לשלוח לכם הודעות הלוך ושוב במהלך תהליך הבדיקה.

הצעת מדריך

הגדרה בפעם הראשונה

אם זו הפעם הראשונה שאתם שולחים הדרכה למאגר GitHub של קהילת Earth Engine, הקפידו לבצע את השלבים הבאים לפני שתתחילו לעבוד על ההדרכה:

1. מאשרים את הסכם הרישיון לתורמים (CLA) בכתובת:

   https://cla.developers.google.com

2. חשוב לקרוא את מדריך הסגנון ליצירת מדריכים לקהילה ולהפנים אותו.

כתיבה ושליחה של מדריך

אחרי שהצעת המדריך שלכם תאושר על ידי המפתחים, יהיו לכם כמה אפשרויות לעריכת המדריך ולשליחתו למאגר הקהילה של Earth Engine:

התחלה מהירה עם Markdown

אתם יכולים ליצור עותק של מאגר GitHub וליצור מדריך חדש ישירות דרך אתר GitHub כדי להתחיל במהירות בלי כלים נוספים או הגדרות:

1. אם עדיין לא עשיתם את זה, נכנסים ל-GitHub.

2. כדי ליצור ולערוך קובץ הדרכה חדש, לוחצים על הדרכה חדשה. אם צריך, תתבקשו ליצור עותק של המאגר.

   מדריך חדש

3. מזינים שם לקובץ ההדרכה של הטופס:

   your-tutorial-name/index.md

   כאשר your-tutorial-name הוא השם המקוצר של ההדרכה באותיות קטנות. משתמשים במקפים ('-') כדי להפריד בין מילים. אין להשתמש ברווחים או בסימני פיסוק אחרים בשם התיקייה.

4. אפשר לערוך את ההדרכה ישירות בעורך הקבצים של GitHub, ולהשתמש באפשרות 'תצוגה מקדימה' כדי לוודא שהפלט מעוצב (אפשר גם לעיין במאמר עריכת קבצים במאגר במאמרי העזרה של GitHub).

5. כשמוכנים, שומרים את השינויים ופותחים בקשת משיכה.

notebook של Colab

כדי להתחיל לכתוב מדריך ב-Colab, לוחצים כאן:

מדריך חדש ל-Colab

ייפתח מחברת עם הוראות ליצירה ולשליחה של המדריך.

הגדרות מתקדמות

אם אתם כבר מכירים את GitHub,‏ git וכלים קשורים, התהליך הכולל לשליחת מדריכים בפורמט Markdown ובפורמט Colab הוא זהה:

1. משכפלים את המאגר google/earthengine-community ב-GitHub ומחברים אותו.

2. יוצרים ספרייה מתחת ל-tutorials עם השם המקוצר של המדריך אחרי המרת התווים (לדוגמה, tutorials/my-amazing-tutorial).

3. מוסיפים את הכותרת המתאימה ל-Markdown או ל-Colab.

4. מבצעים Commit של המדריך לספרייה החדשה עם שם הקובץ index.md (ל-Markdown) או tutorial.ipynb (ל-Colab). העברת התמונות שבהן נעשה שימוש במדריך לאותה תיקייה.

5. שולחים את התוכן החדש למזלג ופותחים בקשת משיכה.

כשיוצרים בקשת משיכה, חשוב להפנות להצעה המקורית באמצעות מספר הבעיה ב-GitHub בקטע התגובות. לדוגמה, אם הבעיה הייתה #123, צריך להוסיף את הטקסט "Closes #123" לתיאור של בקשת המשיכה כדי להפנות להצעה המקורית ולסמן אותה אוטומטית כהצעה שבוצעה אחרי פרסום המדריך.

אחרי שפותחים בקשת מיזוג, מוקצה בדרך כלל מפתח אחד או יותר לבדיקת השליחה. הבודקים יעבדו איתכם כדי לוודא שהשליחה שלכם מלאה, נכונה ועומדת בדרישות של מדריך הסגנון של הקהילה של Earth Engine.

אחרי שבקשת המיזוג תאושר, המדריך יפורסם על ידי האחראים על המאגר.