چرا باید برای کتابخانه‌های متن‌باز خود مستندات خوب بنویسیم؟

تا همین چندسال اخیر، توسعه‌دهندگان اغلب هنر نوشتن مستندات و ارزش داشتن مستندات مناسب را دست‌کم می‌گرفتند. اگر به ده سال پیش نگاهی بیندازید، کتابخانه‌های زیادی پیدا می‌کنید: هم پرکاربردترین آن‌ها و هم کتابخانه‌های بدون مستندات خوب و یا حتی بدون مستند‌نویسی. 

توسعه‌دهندگان اغلب باور دارند که تعدادی مثال برای تازه‌واردان که می‌خواهند آنچه در ذهن آن‌ها می‌گذرد را درک کنند و روش استفاده از کارشان را بدانند، کافی است. هرچند رشد کتابخانه‌های متن‌باز مستلزم این است که مستندات بیشتری با درنظر گرفتن کاربر نهایی نوشته شوند. 

مؤسسات متوجه شدند که حضور در دنیای متن‌باز یک تلاش ارزشمند برای جذب کارفرماها و توسعه‌دهندگان جدید است. پروژه‌های متن‌باز موجب شهرت و اعتبار می‌شوند؛ بنابراین انگیزه نوشتن مستندات قوی اهمیت بیشتری پیدا کرد.

دلیل دیگری که من در درجه اول برای رشد میزان محبوبیت فناوری Node ذکر می‌کنم، کتابخانه‌های رقیب در جامعه است؛ موقعیتی که به‌ندرت قبل از ورود npm دیده می‌شد. 

به‌عنوان‌مثال در پایتون اغلب یک راه برای انجام یک کار وجود دارد. در جاوااسکریپت هم قبل از Node، کتابخانه‌های زیادی برای انجام دادن یک کار به روش‌های مختلف وجود ندارد؛ کافی است به گزینه‌های محبوب jQuery فکر کنید.

 امروزه ما می‌توانیم stack مربوط به فناوری خودمان را انتخاب کنیم و توسعه‌دهندگان این کتابخانه‌ها و فریم‌ورک‌ها تلاش زیادی برای یادگیری و استفاده سریع از آن‌ها انجام می‌دهند. 

توسعه‌دهندگان جاوااسکریپت امکان انتخاب بین Angular ،React ،Vue و بسیاری دیگر از فریمورک‌‌‌هایی در زمینهٔ front-end را دارند.

اجزای یک مستند مناسب

بخش‌های زیادی برای یک مستند وجود دارد که از بین آن‌ها به موارد زیر اشاره می‌کنیم:

• فایل Readme
• مرجع
• راهنما
• کتاب‌ها
• پست وبلاگی

هرکدام از این‌ها اهداف مختلفی را برآورده می‌کنند و مرز بین انواع مستند، گاهی اوقات ناپدید می‌شود.

Readme

فایل readme اغلب اولین ارتباط کاربران بالقوه با محصول شما است. می‌توان آن را تا حدی ترکیبی از مستندات دیگر درنظر گرفت، اما از بعضی جهات شبیه هیچ‌کدام آن‌ها نیست. Readme روش ارائه کتابخانه متن‌باز شماست؛ اما لازم به ذکر است که باید مختصر و آموزنده باشد.

ابتدا مواردی را که کتابخانه شما به آن کمک می‌کند و مشکلاتی را که قادر به حل ‌آن‌هاست، توضیح دهید. می‌توانید چند مثال برای موارد رایج هم بیان کنید. پاراگراف اولیه‌ای که خوب نوشته‌شده باشد، یک شروع عالی برای فایل readme است. اگر فایل readme شما بیشتر از یک صفحه و نیم می‌شود، بهتر است که از جدول اجزا در آن استفاده کنید.

موارد وابسته و پیش‌نیازهایی را که کاربر باید داشته باشد، لیست کنید و مراحل نصب را توضیح دهید. یک مثال پایه‌ای از کد نشان دهید که بهتر است یک مثال واقعی باشد و آن را به مستندات با جزئیات بیشتر لینک کنید.

درنهایت، باید شامل مجوز و فهرست همکاران باشد. می‌توانید یک پاراگراف توضیحی درمورد نحوه کمک به کتابخانه‌تان را هم به آن ضمیمه کنید. به یاد داشته باشید که کتابخانه متن‌باز براساس احترام به وقت همدیگر است و اگر همکاران بالقوه شما بتوانند سرعت اجرای کتابخانه‌تان را افزایش دهند، همه از آن سود می‌برند.

مرجع

 مرجع احتمالاً فنی‌ترین بخش از مستندات شما است. هدف آن فهرست کردن تمام توابعی است که کتابخانه در اختیار شما قرار می‌دهد: ورودی‌های قابل‌انتظار، خروجی‌ها و عوامل جانبی، اهداف و نمونه‌های اجرایی. نمونه‌ها در مرجع باید منفرد و تا جایی که ممکن است وابسته به خود باشند.

یک مرجع اغلب بارها به‌صورت خودکار تولید می‌شود و چندین راه‌حل‌ وجود دارد که کار کردن با آن را ساده و آن را بروزرسانی می‌کند؛ به‌هرحال شما باید به یاد داشته باشید درک مرجعی که کاملاً توسط کامپیوتر تولید می‌شود ممکن است برای کاربران دشوار باشد. شما باید تلاش کنید که حداقل یک جمله توضیحی برای هر مورد در مرجع قرار دهید.

برای بعضی از توسعه‌دهندگان هم درک چگونگی اجرای یک تابع خاص می‌تواند مفید باشد. یکی از ویژگی‌های خوب که چندان هم ضروری نیست، لینک مستقیم به اجرای تابع در کد کتابخانه شما است.

راهنما

یک راهنما درواقع یک آموزش‌نامه است که به کاربر شما کمک می‌کند تمام ویژگی‌های کتابخانه شما را شناسایی کند. در مقیاس بزرگ‌تر، اهداف عمومی و قالب‌های کاری نظری، راهنما می‌تواند بزرگ‌ترین بخش یک مستند باشد.

راهنمای خود را این‌گونه آغاز کنید: ابتدا دامنه آن و سپس دانش و اطلاعاتی را که لازم است کاربر بداند، معرفی کنید. به‌عنوان‌مثال اگر کتابخانه‌ای دارید که به درخواست‌های مدیریتی HTTP کمک می‌کند، از کاربر انتظار می‌رود که لااقل با مفاهیم پایه این موضوع آشنا باشد.

به این صورت شروع کنید که ابتدا پایه‌ای‌ترین موضوعات را پوشش دهید و به‌تدریج به سمت مفاهیم پیچیده‌تر بروید. یک نقطه خوب برای شروع همیشه معرفی مراحل نصب برای سیستم‌های مختلف است. 

به این شکل تصور کنید که یک عده از مردم روبروی شما نشسته‌اند و شما می‌خواهید محصولتان را برای آن‌ها توصیف کنید. به یاد داشته باشید که در این مورد برای کاربران اینکه بیش‌ازحد توضیح بدهید تا اینکه مفاهیم مهم را واضح بیان نکنید، محترمانه‌تر است. 

در مثال‌های کدنویسی، در مواردی که لازم است از عکس و نمودار استفاده کنید. ممکن است شما بخواهید که تا حد ممکن کد کاملی را در مستندات ایجاد کنید که کاربرد بتواند به‌سادگی قسمت‌های خاص را کپی-پیست کند، اما باید به‌صورت منطقی از توضیحات و تبصره‌هایی که درمورد کاربردهای عمومی ویژگی‌های مثال‌زده شده در کد آمده است، جدا شوند.

به یاد داشته باشید که راهنمای خودتان را امتحان کنید. کاربر باید بتواند هر مثالی از کد را، کپی-پیست کند. من به‌اندازه کافی نمی‌توانم تأکید کنم که برای کاربر تا چه اندازه آزاردهنده است اگر مثال‌های کد که در مستندات به آن‌ها اشاره می‌شود، کار نکنند.

کتاب‌های راهنما

در مقیاس بزرگ و برای کتابخانه‌های با اهداف عمومی، کتاب‌های راهنما (cookbook) مجموعه‌ای از راه‌حل‌های عمقی برای مشکلات رایجی است که کاربر شما ممکن است در زمان استفاده از کتابخانه شما با آن‌ها مواجه شود. برخلاف راهنما که براساس مفاهیم اولیه ساخته می‌شود، هر دستوری در cookbook باید وابسته به‌خود باشد. کاربرد ویژگی‌های ضروری برای حل مسائل هم باید با جزئیات بیشتری نسبت به راهنما ذکر شوند.

استفاده از Cookbookها در موارد کوچک و کتابخانه‌های متمرکز ضروری نیست و فقط زمانی درنظر گرفته می‌شوند که مفاهیمی با پیچیدگی‌های بیشتر وجود داشته باشند و نتوان ازنظر منطقی آن‌ها را در بخش راهنما قرار داد. به همین صورت، cookbook می‌تواند به‌عنوان مجموعه‌ای از آموزش‌های کوتاهی درمورد چگونگی دست یافتن به نتیجه مطلوب درنظر گرفته شود.

علاوه بر این، درحالی‌که بخش راهنما در درجه اول روی کتابخانه خودتان تمرکز می‌کند، در دستورات cookbook، ارتباط با سایر مستندات و نشان دادن یکپارچگی با سایر کتابخانه‌ها ذکر می‌شود. درنهایت شما می‌توانید بیان کنید که چرا از بعضی از ویژگی‌های زبان بیشتر از دیگران استفاده کردید. این به کاربرتان کمک می‌کند که نه‌تنها در استفاده از کتابخانه شما مهارت بیشتری کسب کند، بلکه به‌طورکلی در زبان برنامه‌نویسی ماهرتر شود.

درنهایت شما می‌توانید مثال‌هایی بیاورید در خصوص اینکه چه زمانی نباید از راه‌حل‌های خاص استفاده شود و یا اینکه مثال‌هایی از کدهای نادرست یا ضدالگوهای برنامه‌نویسی را نمایش دهید. به‌هرحال به یاد داشته باشید که آن‌ها باید از مثال‌های صحیح به‌خوبی قابل‌تشخیص باشند.

پست وبلاگ

یک پست وبلاگی درحالی‌که ممکن است کاملاً بخشی از مستندات نباشد اما یک قسمت مهم از اطلاعاتی است که کاربر شما بابت آن از شما قدردانی می‌کند. درحالی‌که سایر بخش‌های مستندات روی چگونگی استفاده از کتابخانه شما با موارد مربوطه تمرکز می‌کند، پست وبلاگ شما باید بیان کند که در وهله اول چرا به آن نیاز بوده است.

در پست وبلاگ، شما با کاربرانتان ارتباط برقرار می‌کنید و به آن‌ها می‌گویید که چرا راه‌حل شما از دیگران بهتر است. شما می‌توانید درمورد مسائلی که باعث شدند انگیزه‌ای برای نوشتن کتابخانه پیدا کنید، بنویسید و دلایلی مبنی بر وجود آن‌ها ارائه دهید.

لازم به ذکر است که برخلاف اسم آن، شما نیازی به وبلاگ برای نوشتن پست وبلاگی ندارید: می‌توانید این کار را در Github  انجام دهید و لینک آن را در readme قرار دهید.

قبل از انتشار

نحوه ثبت مستندات مهم است، خواندن مستنداتی که دستور زبان و نگارش ضعیفی دارند به‌سرعت برای فرد خسته‌کننده می‌شود. متن مستندات خود را به یک فرد انگلیسی‌زبان و یا یک فرد باتجربه در زبان انگلیسی نشان دهید، که به شما در این خصوص کمک کند. 

اگر امکان استفاده از این گزینه را ندارید، به همکارانتان اجازه دهید که درخواست کمک را برای شما ارسال کنند و یا حتی این درخواست را با آن‌ها در فایل readme مطرح کنید. تعدادی ابزار خودکار برای این منظور در دسترس هستند که می‌توانند به شما کمک کنند مثل Grammarly و Hemingway.

سخن پایانی

در عصر حاضر که تِرندهای توسعه به‌صورت مداوم در حال تغییر هستند، مستندسازی از هر زمان دیگری اهمیت بیشتری پیدا کرده است. به کاربرانتان اجازه دهید که سرعت خودشان را در استفاده از کتابخانه شما افزایش دهند و به آن‌ها کمک کنید که آن را یاد بگیرند و این یک فاکتور مهم در انتشار پروژه شما در دنیای متن‌باز است.

و علاوه بر این، نوشتن مستند آن‌قدرها هم بد نیست!

منبع