מבוא
Codelab הוא מדריך אינטראקטיבי שנכתב בתחביר Markdown. אנחנו מפרסמים את ה-Codelabs שלנו בכתובת blocklycodelabs.dev. ב-Codelabs נעשה שימוש בשילוב של שפה טבעית, דוגמאות קוד וצילומי מסך כדי ליצור חוויית הדרכה מעניינת יותר. המשתמש שמיועד ל-codelab עוקב אחרי ההוראות ומריץ את הקוד תוך כדי הקריאה.
כתיבת Codelab היא דרך מצוינת לתרום לקהילה. זו דרך לשתף את הידע שלכם ולעזור למפתחים אחרים שנתקלים באותה בעיה.
מה הופך קוד לאב למוצלח?
קודלאב טוב הוא ממוקד וקריא. המדריך מסביר למשתמשים בצורה ברורה מה הם יבנו ומה הם ילמדו, ומנחה אותם בכתיבת קוד ובהבנתו כדי להשלים משימה ספציפית.
עיבוד
אם יש לכם רעיון ל-codelab, אתם יכולים לספר לנו עליו באמצעות בקשה לתכונה במאגר blockly-samples. כדאי לכלול תיאור של מה שרוצים ללמד ומה יבנו בסדנת התכנות. נדון ברעיון ונשפר אותו. אחר כך תוכלו לכתוב את הקוד ולשלוח בקשת משיכה בשבילו. אחרי שהפריט יעבור בדיקה, אחד מחברי צוות Blockly יפרסם אותו.
טיפים לגבי כתיבה
בהמשך הדף מופיעות שאלות וטיפים שיעזרו לכם לכתוב קוד לאב.
כדאי לעיין במאמר Technical Writing One כדי לקבל מבוא קצר לכתיבה טכנית.
קהל
- מי קהל היעד?
- מה הם כבר יודעים על השימוש ב-Blockly?
- מה הם מנסים ללמוד?
הגדרה
- מהי ההגדרה המינימלית שנדרשת כדי שהמשתמש יוכל להריץ את הקוד?
אם זה יעזור, תוכלו לפרסם קוד התחלתי וקוד מלא בספרייה examples.
מבנה
כמו בכל כתיבה, מתחילים עם ראשי פרקים. זהו מבנה טוב לרוב ה-codelabs:
- מבוא
- מה תלמדו
- מה תפַתחו
- מה כדאי לדעת
- הוראות התקנה
- שלב ראשון: [כאן מזינים את הכותרת]
- הסבר או מוטיבציה
- דוגמת קוד
- התוצאות הצפויות
- (אופציונלי) הסבר נוסף
- ...
- שלב עשירי: [כאן מזינים את הכותרת]
- סיכום
- מה למדתם
- מה יצרתם
- מקורות מידע נוספים
- קישור לקוד שהושלם (אם זמין)
אפשר להשתמש ביותר מעשרה שלבים, אבל אם אתם מגיעים לעשרים, כדאי לפצל את המדריך לשני מדריכים.
סגנון כתיבה
- להשתמש בסגנון כתיבה שיחתי.
- כדאי להשתמש בכותרות כדי שהארגון יהיה ברור.
- כדאי להשתמש ברשימות עם תבליטים כדי לפצל קירות של טקסט.
- אפשר להשתמש בתמונות ובקובצי GIF!
סגנון קוד
- אפשר לכתוב ב-ES5, ב-ES6 או ב-TypeScript, אבל צריך לציין לקורא באיזו שפה מדובר בתחילת הקטע.
- פועלים לפי מדריך הסגנון של Google