معرفی
Codelab یک آموزش تعاملی است که با نحو علامت گذاری نوشته شده است. ما کدهای خود را در blocklycodelabs.dev منتشر می کنیم. Codelabs از ترکیبی از زبان طبیعی، نمونه کد و اسکرین شات استفاده می کند تا تجربه آموزشی جالب تری ایجاد کند. کاربر هدف یک Codelab در حال دنبال کردن و اجرای کد هنگام خواندن است.
نوشتن یک کد یک راه عالی برای کمک به جامعه است. این راهی است برای به اشتراک گذاشتن دانش خود و آسان‌تر کردن زندگی برای توسعه‌دهنده بعدی که با همین مشکل مواجه می‌شود.
چه چیزی یک Codelab عالی را می سازد؟
یک Codelab عالی متمرکز و قابل خواندن است. به طور واضح به کاربر می‌گوید که چه چیزی بسازد و چه چیزی را یاد خواهد گرفت، و کاربر را در نوشتن و درک کد راهنمایی می‌کند تا یک کار خاص را انجام دهد.
روند
اگر ایده‌ای برای یک Codelab دارید، می‌توانید با درخواست ویژگی در مخزن نمونه‌های بلوک، در مورد آن به ما بگویید. شرحی از آنچه می خواهید آموزش دهید و آنچه را که خواهید ساخت در نرم افزار Codelab اضافه کنید. ما در مورد ایده بحث و اصلاح خواهیم کرد. سپس می توانید آن را بنویسید و یک درخواست کشش برای آن ارسال کنید . پس از بررسی ، یکی از اعضای تیم Blockly آن را منتشر خواهد کرد.
نکات نوشتن
بقیه این صفحه مجموعه ای از نکات و سوالاتی است که شما را در نوشتن یک کد لبه راهنمایی می کند.
برای آشنایی سریع با رایتینگ فنی ، Technical Writing One را بررسی کنید.
حضار
- خواننده هدف کیست؟
- آنها قبلاً در مورد استفاده از Blockly چه می دانند؟
- آنها سعی می کنند چه چیزی را یاد بگیرند؟
برپایی
- حداقل تنظیمات مورد نیاز کاربر برای اجرای کد شما چیست؟
اگر مفید بود، می‌توانید کد شروع و کد تکمیل‌شده را در فهرست examples منتشر کنید.
ساختار
مانند هر نوشته دیگری، با یک طرح کلی شروع کنید. این یک ساختار خوب برای اکثر کد لبه ها است:
- معرفی
- چیزی که یاد خواهید گرفت
- چیزی که خواهی ساخت
- چه چیزی میخواهید بدانید
- دستورالعمل های راه اندازی
- مرحله اول: [عنوان اینجاست]
- توضیح / انگیزه
- نمونه کد
- نتایج مورد انتظار
- (اختیاری) توضیح بیشتر
- ...
- مرحله دهم: [عنوان اینجاست]
- خلاصه
- چیزی که یاد گرفتی
- چیزی که ساختی
- منابع اضافی
- پیوند به کد تکمیل شده (در صورت موجود بودن)
در حالی که می توانید بیش از ده مرحله داشته باشید، اگر بیست مرحله را می گذرانید، باید آن را به دو صفحه کد تقسیم کنید.
سبک نوشتن
- از سبک نوشتاری محاوره ای استفاده کنید.
- از سرفصل ها برای شفاف سازی سازمان استفاده کنید.
- از لیست های گلوله ای برای شکستن دیوارهای متون استفاده کنید.
- از تصاویر و گیف استفاده کنید!
سبک کد
- می توانید در ES5، ES6 یا TypeScript بنویسید، اما در ابتدا به خواننده بگویید که کدام است.
- راهنمای سبک گوگل را دنبال کنید