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