نحوه نوشتن یک راهنما
این یک راهنما برای نوشتن آموزشها (tutorial) درباره Nix است.
منظور ما از راهنماها، درسهایی است که در چارچوب Diátaxis برای مستندات فنی توصیف شدهاند، و توصیه میکنیم پیش از ادامه، با Diátaxis آشنا شوید. بهویژه تفاوت بین آموزشها و راهنماها را مدنظر قرار دهید.
مخاطبان هدف
مخاطبان اصلی آموزشهای Nix، توسعهدهندگان نرمافزاری هستند که حداقل تجربه پایه را در خط فرمان لینوکس دارند.
پاسخگویی آنی متخصصان به سوالات، دستورالعملها و آموزشهای شخصیسازیشده، و سایر اشکال کارآموزی، شناختهشدهترین روشهای حمایتی برای یادگیری Nix هستند. این آموزشها برای کسانی طراحی شدهاند که به هیچیک از این موارد دسترسی ندارند، و بنابراین باید بهگونهای نوشته شوند که برای یادگیری خودهدایتشونده مناسب باشند. این امر با پیروی از ساختار ذکر شده در اینجا محقق میشود که ویژگی اصلی آن تلاش برای جلوگیری و برطرف کردن تمام خلأهای اطلاعاتی برای یادگیرنده است.
به عنوان یک محصول جانبی، یک آموزش خوشنوشته به عنوان یادداشتهای سخنرانی برای استفاده در جلسات آموزشی تعاملی مفید خواهد بود. بنابراین، مخاطبان ثانویه، مربیانی هستند که Nix را تدریس میکنند.
فرآیند
نوشتن یک آموزش باکیفیت زمان میبرد، هم برای شما و هم برای دیگران. بیشتر این زمان معمولاً صرف موارد مشارکتی زیر میشود:
- پیدا کردن رویکرد درست
- اطمینان از اینکه دستورالعملها برای یادگیرندگان نه خیلی مختصر هستند و نه خیلی فشرده
- یافتن روشهای روزافزون موجزتر و روشنتر برای انتقال ایده
برای جلوگیری از انجام کار دوباره، این مراحل را دنبال کنید:
انتخاب یک موضوع
یک موضوع پیگیری برای آموزشهایی وجود دارد که تیم مستندات تصمیم گرفته است باید به عنوان بخشی از مجموعه آموزشی وجود داشته باشند. موضوعی را انتخاب کنید که به آن تسلط دارید یا علاقه خاصی به آن دارید.
موضوعات و درخواستهای پول ریکوئست (pull request) ارجاعشده را بررسی کنید تا مطمئن شوید کاری را که شخص دیگری قبلاً شروع کرده است، تکرار نمیکنید.
درخواستهای آموزشی بیشتری نسبت به موارد ذکر شده در کلیات وجود دارد. اگر موضوعی که میخواهید روی آن کار کنید در هیچ کجا پیگیری نمیشود، یک موضوع جدید باز کنید. این یک فرصت برای شماست تا اهداف خود را روشن کنید، و فرصتی برای دیگران است تا متوجه شوند که به آن موضوع علاقه وجود دارد.
ارسال یک پول ریکوئست همراه با ساختار کلی
یک پول ریکوئست همراه با ساختار کلی (outline) آموزش و با پیروی از ساختار پیشنهادی ما ارسال کنید. ساختار کلی باید حاوی نکات گلولهای (bullet points) درباره محتوای هر بخش باشد. برای اعلام اینکه در حال کار بر روی یک آموزش هستید، از طریق توضیحات پول ریکوئست به موضوع پیگیری ارجاع دهید.
بررسی (review) تضمین میکند که از نظر اهداف یادگیری و پیادهسازی فنی در مسیر درستی قرار دارید.
بسط دادن ساختار کلی
محتوای آموزش را با پیروی از ساختار کلی خود و style-guide گسترش دهید.
یک بررسی تضمین میکند که تمام اطلاعات مورد نیاز را بدون تحتفشار گذاشتن یادگیرندگان، به ترتیب درست دریافت میکنید.
پیگیری نظرات بازبینی
آموزش خود را بر اساس بازخورد دقیق اصلاح کنید. توصیه میکنیم آموزش خود را با دوستان یا همکاران خود آزمایش کنید. این کار هم به آشکار کردن پیشنیازهای ضمنی کمک میکند و هم تخمین واقعبینانهای از زمان مطالعه ارائه میدهد.
یک بررسی نهایی بررسی میکند که همهچیز از نظر فنی درست باشد.
ساختار
هر آموزش باید به سوالات زیر پاسخ دهد.
علاوه بر این، ما به شدت کتاب How Learning Works (summary) را به عنوان راهنمایی برای طراحی مطالب آموزشی پیشنهاد میکنیم.
چه چیزی خواهید آموخت؟
بیان مسئله و اهداف یادگیری.
هدف یادگیری یک آموزش همیشه کسب یک مهارت است که ویژگی آن قابلاجرا بودن در مجموعه ای از موقعیتها با الگوهای تکرارشونده است.
به چه چیزهایی نیاز دارید؟
دانش و مهارتهای پیشنیاز را بیان کنید. این آموزش باید همیشه به گونهای نوشته شود که پیشنیازهای ذکرشده برای دستیابی به اهداف یادگیری کافی باشند.
مثالها:
- پیوندها به فصول قبلی
- مهارتها یا دانش مخصوص حوزه
چقدر زمان میبرد؟
زمان مطالعه را تخمین بزنید. این کار برای فراگیران مهم است تا مطمئن شوند ظرفیت لازم برای انجام کارهای برنامهریزیشده را دارند و در نتیجه از سرخوردگی جلوگیری کنند؛ سرخوردگیای که ممکن است مانع از ادامه مسیر آنها در بومسازگان Nix شود.
این تخمین به دانش و مهارت ازپیشموجود فراگیر بستگی دارد. میتوانید اشاره کنید که چگونه مهارتها یا دانش اختیاری ممکن است بر زمان مطالعه تأثیر بگذارند.
چه باید بکرد؟
مراحل رسیدن به هدف یادگیری را ارائه دهید. این موارد باید به شکل دستورالعملهای مستقیمی باشند که به طور تکرارپذیر به نتیجه مطلوب منتهی میشوند.
همچنین ارزشمند است که توضیحات متنی را در بلوکهای :::اضافه کنید.
این کار میتواند به درک مطلب کمک کند و در عین حال عوامل حواسپرتی را به حداقل برساند.
چه چیزی آموختید؟
تمرینها یا مثالهای حلشده و ابزارهای دیگری برای خودسنجی ارائه دهید.
این همچنین جای خوبی است تا به خوانندگان راههایی برای بازخورد دادن یا پرسیدن سوال از نویسندگان پیشنهاد کنید تا به بهبود آموزش ادامه دهید.
گامهای بعدی
بسته به اینکه یک مورد استفاده چقدر بررسی شده است، خواننده را به موارد زیر ارجاع دهید:
- راهنماهای مرجع
- راهنماها یا آموزشهای دیگر
- پیوندهایی به منابع خارجی تاییدشدهٔ سالم، همراه با خلاصهها
- بررسی اجمالی ابزارهای پشتیبانی موجود، وضعیت بلوغ و نگهداری آنها
- بررسی اجمالی ایدهها و وضعیت بحثهای جامعهٔ کاربری.
توصیه میکنیم جداسازی صریحی بین منابع یادگیری عملی و نظری انجام دهید، زیرا در این صورت خوانندگان قادر خواهند بود به سرعت تصمیم بگیرند که یا کارها را انجام دهند یا بیشتر بیاموزند.
منابع خارجی باید دارای یک خلاصه برای تعیین انتظارات باشند که ایدهآل آن شامل زمان مطالعه است.
پستهای وبلاگ باید عنوان اصلی خود را در پیوند و(<author>, <year>) داشته باشند:
به نویسندگان اعتبار دهید، و به خوانندگان ایدهای بدهید که اطلاعات تا چه حد بهروز است.