سفر توسعه وب با یاقوت روی ریل در سال گذشته کاملاً سواری ترن هوایی بوده است. من هزاران چیز را در مورد نحوه سازماندهی داده ها و ایجاد پایگاه های داده موثر یاد گرفته ام. اما یک چیزی که من به طور کامل از آن صرف نظر کردم در حالی که در اطراف زمین یاقوت بودم این بود که مردم چه چیزهایی را هنگام نوشتن مستندات باید بدانند؟! چه چیزی واجد شرایط مستندسازی خوب است و ساده ترین و مختصرترین راه برای نوشتن اسناد چیست؟
همانطور که با یادگیری خود به جلو رفتم، چیزهای زیادی یاد گرفتم. مرور پروژه‌های گذرانده شده‌ام چیزی است که من را ترغیب کرد تا واقعاً غمگین باشم و روی پاسخ به این سؤال که مستندات خوب به نظر می‌رسند تمرکز کنم. زیرا نکته اصلی این است که مستندات مناسب به اندازه خود کد و آزمایش مهم هستند.
اکنون اسناد زیادی را در سال گذشته خوانده ام. سعی می کنم تا جایی که می توانم در مورد یاقوت و ریل یاد بگیرم و آموخته هایم را به روش های موثر پیاده کنم. و برخی از اسنادی که خواندم عالی بود، در حالی که برخی دیگر بیشتر از پاسخ‌هایی که داشتم، سوالاتی برایم ایجاد کردند.
در حالی که GitHub خود را از پروژه های قدیمی پاک می کنم و پروژه های مورد علاقه خود را بازسازی می کنم. این فرآیند واقعاً عالی بوده است، زیرا نه تنها به میزان رشدم در طول سال گذشته بازنگری کرده‌ام، بلکه تلاش برای اشکال‌زدایی کدهای قدیمی و تبدیل آن به بیت‌های کد کارآمدتر، چالش برانگیز است. نقاط گلوله زیر بخشی از چیزهایی است که در طول مسیر یاد می‌گیرم و برخی از سوالاتی است که سعی می‌کنم در حین بازسازی این مخزن‌ها از خودم بپرسم:
یک برنامه نویس غیر روبی برای اجرای این پروژه چه چیزهایی را باید بداند؟
- هر روز هزاران توسعه دهنده جدید وارد دنیای کد می شوند. برخی از چیزهایی که آرزو می‌کردم بیشتر ببینم، مخزن‌هایی بودند که فرض می‌کردند درباره برنامه‌ای که می‌نویسند چیزی نمی‌دانم.
این پروژه چه کاری انجام می دهد؟
- چه این یک بازی کارتی باشد که در ترمینال بازی می شود، یک برنامه تمام پشته یا فقط یک api. شخص دیگری که در سمت دیگر readme قرار دارد باید بتواند به readme نگاه کند و بفهمد که با برنامه ای که به آن نگاه می کند چه کاری می تواند انجام دهد.
اهداف این پروژه چیست؟
- این ممکن است خیلی مهم نباشد، اما من همیشه دوست داشتم که اهداف اولیه پروژه را بخوانم و همچنین آنچه را که توسعه دهنده به دنبال کار روی آن در آینده است. پیگیری رشد برنامه های خود بسیار جالب است.
در فهرست مطالب من، هدرهای مهمی که افراد ممکن است به دنبال پیوندهای سریع باشند چیست؟ (در زیر مواردی هستند که من به آنها تمایل دارم)
- شرح پروژه
- اجرا و نصب کنید: چه جواهری در این برنامه وجود دارد؟ چگونه آنها را نصب کنم یا کاربر به چه پیوندهایی به اسناد نیاز دارد تا بتواند آنها را به درستی نصب کند.
- کاربر چگونه از برنامه در لوکال هاست استفاده می کند؟
- نقاط پایانی: صراحتاً چه مسیرهایی وجود دارد و چه چیزی باید انتظار بازگشت داشته باشم
- معماری و طراحی: جداول چه شکلی هستند و چگونه به هم مرتبط هستند؟
- بازخورد: لزوماً الزامی نیست، اما من این ایده را دوست داشتم که مردم در شرف ایجاد درخواست‌های کششی برای ایجاد تغییرات/اشتراک‌گذاری ایده‌ها در یک پروژه باشند، بنابراین من در تلاش هستم تا این را به همه پروژه‌هایم اضافه کنم.
- وام: فراموش نکنید که برای کاری که در این پروژه انجام داده اند به شما و همه همکاران اعتباری بدهید! من دوست دارم پروفایل های LinkedIn و GitHub خود را به هم متصل کنم تا افراد بتوانند در صورت داشتن سوال با من تماس بگیرند
این چیزی است که من تا کنون دریافته ام که در راهنمایی برای ایجاد خواندنی ترین و خواندنی ترین مطالب مفید بوده است. اگر پیشنهادی در مورد چیزهایی دارید که هنگام ایجاد مستندات مفید بوده‌اید، در نظرات به من بگویید!
