چارچوب مستندسازی
هدف ما ساخت مستندات خود بر اساس چارچوب Diátaxis برای مستندات فنی است که مستندات را به چهار دسته تقسیم میکند:
ما متوجه شدهایم که مشارکتکنندگان برای درک تفاوتهای میان این دستهها دچار مشکل میشوند، و در حالی که بهشدت توصیه میکنیم دربارهی چارچوب Diátaxis مطالعه کنید، میتوانیم آنها را به شرح زیر خلاصه کنیم:
مرجع
محتوای مرجع باید
- روی «آنچه وجود دارد» تمرکز کند و به سادگی توابع، کلاسها و غیره موجود را فهرست کند
- از زبانی مختصر استفاده کند و متن و چیدمان برای اسکن کردن و دسترسی تصادفی بهینهسازی شده باشند
- نمونههای استفادهی مرتبط و کاملی را نشان دهد
- برای قابلیت کشف بهتر، به موارد مرتبط پیوند دهد
آموزشها
آموزشها کاربر را در یک فعالیت خاص همراهی میکنند تا ابزارها و الگوهای رایج در بومسازگان را به او بیاموزند. در حالی که خود آن فعالیت مهم است، هدف این است که نقطهها را بین سایر چیزهایی که خواننده آموخته است به هم متصل کنیم.
ساختار آموزشها باید بار شناختی روی یادگیرندگان را به حداقل برساند و بهطور فعال از انتخابها و فرصتهای بروز خطای کاربری جلوگیری کند.
راهنماها
راهنماها فهرستی از مراحل هستند که نحوه دستیابی به یک هدف خاص یا حل یک مشکل خاص را نشان میدهند. هدف این است که به خواننده کمک شود به یک نتیجهی خاص برسد، نه اینکه تئوری زیربنایی یا زمینه گستردهتر را درک کند.
یک راهنما فرض میکند که خواننده از پیش پسزمینهی لازم برای درک موضوع مورد بحث را دارد و بنابراین نیازی به توضیح مقدمهی هر مفهوم جدید ندارد.
مفاهیم
مفاهیم درونمایهی یک قطعه کد یا نحوهی تفکر دربارهی یک ایده یا موجودیت خاص در بومسازگان را توصیف میکنند. یک مفهوم همچنین میتواند زمینهی تاریخی این موضوع را توصیف کند که چرا یک چیز به شکل امروزیاش کار میکند.
اگر متوجه شدید که میخواهید دربارهی جزئیات دقیق و ریزهکاریهای نحوهی کارکرد چیزی بنویسید، احتمالاً میخواهید یک متن توضیحی بنویسید.
راهنماها در مقابل آموزشها
ما متوجه شدهایم که مشارکتکنندگان عمدتاً با تفاوت بین یک راهنما و یک آموزش دستوپنجه نرم میکنند.
در اینجا چند توضیح برای کمک به درک تفاوت آورده شده است.
- یک راهنما در یک زمینهی «کاری» استفاده میشود که در آن خواننده فقط به دنبال دنبالهای از دستورالعملها برای دستیابی به یک نتیجه است.
- در این زمینه ممکن است خواننده از پیش بداند یا برایش مهم نباشد که این دستورالعملها چگونه یا چرا کار میکنند، او فقط میخواهد بداند برای دستیابی به نتیجهی مطلوب چه کاری باید انجام دهد.
- یک آموزش در یک زمینهی «یادگیری» استفاده میشود که در آن خواننده برای کسب تمرین در انجام یک کار خاص، دنبالهای از دستورالعملها را دنبال میکند.
- بخشهای کوچکی از انگیزه یا توضیح در این زمینه مفید هستند تا به خواننده کمک کنند نقطهها را با سایر چیزهایی که ممکن است از پیش آموخته باشد به هم وصل کند، اما تمرکز روی فعالیت است، نه روی چگونه یا چرا.
یک تمثیل مفید، فرود آوردن یک هواپیما در دو زمینهی مختلف است.
فرض کنید خلبان بیهوش است و شما اکنون باید هواپیما را بنشانید تا از یک کرش کردن جلوگیری کنید. در این زمینه شما فقط میخواهید بدانید چگونه نمیرید. برای شما مهم نیست که چگونه یا چرا، شما فقط میخواهید سالم روی زمین باشید. این زمینه برای یک راهنما است.
یک کارآموز خلبانی در یک شبیهساز پرواز می 원د فرود آوردن هواپیما را تمرین کند. این کارآموز خلبانی نیاز به تمرین دارد تا بداند چه زمانی چرخهای فرود (landing gear) را باز کند، چه زمانی فلپها را تنظیم کند و غیره. فرود آوردن واقعی هواپیما در طول شبیهسازی پرواز اهمیت کمتری نسبت به یادگیری مهارتهای فردی دارد که یک فرود موفق را تشکیل میدهند. این زمینه برای یک آموزش است.
در نهایت، آخرین روش برای تفکر دربارهی تفاوت بین یک راهنما (how-to) و یک آموزش (tutorial) به این شکل است:
- راهنما: «گام ۱: این کار را انجام دهید، گام ۲: آن کار را انجام دهید و غیره»
- آموزش: «دست من را بگیر تا به تو نشان دهم چطور این کار را انجام دهی»