כתיבת הדרכה ל-Codelab

מבוא

Codelab הוא מדריך אינטראקטיבי שנכתב בסינטקס של Markdown. אנחנו מפרסמים את ה-Codelabs שלנו בכתובת blocklycodelabs.dev. ב-Codelabs נעשה שימוש בשילוב של שפה טבעית, דוגמאות קוד ותמונות מסך כדי ליצור חוויית לימוד מעניינת יותר. משתמש היעד של Codelab עוקב אחרי ההוראות ומריץ את הקוד בזמן הקריאה.

כתיבת Codelab היא דרך מצוינת לתרום לקהילה. זוהי דרך לשתף את הידע שלכם ולקל על המפתח הבא שייתקל באותה בעיה.

מה הופך סדנת Codelab למצוינת?

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

עיבוד

אם יש לכם רעיון ל-codelab, תוכלו לספר לנו עליו באמצעות בקשת תכונת במאגר blockly-samples. יש לכלול תיאור של מה שרוצים ללמד ומה שתיצרו ב-codelab. נדבר על הרעיון ונשפר אותו. לאחר מכן תוכלו לכתוב על כך בקשת משיכה. אחרי שנבדוק את הקוד, חבר בצוות Blockly יפרסם אותו.

טיפים לגבי כתיבה

בהמשך הדף מפורטות שאלות וטיפים שיעזרו לכם לכתוב Codelab.

בקורס 'כתיבה טכנית' מוסבר על כתיבה טכנית באופן קצר.

קהל

  • מי קהל היעד של הקוראים?
  • מה הם כבר יודעים על השימוש ב-Blockly?
  • מה הם מנסים ללמוד?

הגדרה

  • מהן ההגדרות המינימליות הנדרשות כדי שהמשתמש יוכל להריץ את הקוד שלכם?

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

מבנה

כמו בכל כתיבה, מתחילים עם תוכנית. זהו מבנה טוב לרוב ה-codelabs:

  • מבוא
    • מה תלמדו
    • מה תפַתחו
    • מה כדאי לדעת
    • הוראות התקנה
  • שלב ראשון: [כותרת כאן]
    • הסבר/מוטיבציה
    • דוגמת קוד
    • התוצאות הצפויות
    • (אופציונלי) הסבר נוסף
  • ...
  • שלב עשר: [הכותרת תופיע כאן]
  • סיכום
    • מה למדתם
    • מה יצרתם
    • מקורות מידע נוספים
    • קישור לקוד שהושלם (אם יש כזה)

אפשר ליצור יותר מעשרה שלבים, אבל אם מגיעים ל-20, כדאי לפצל את הקוד למספר סדנאות.

סגנון כתיבה

  • כדאי להשתמש בסגנון כתיבה שיחה.
  • השתמשו בכותרות כדי להבהיר את הארגון.
  • שימוש ברשימות עם תבליטים כדי לפצל קטעי טקסט ארוכים.
  • כדאי להשתמש בתמונות ובקובצי GIF.

סגנון קוד