من به تازگی مقاله ای از تام پرستون-ورنر در مورد چگونگی حل مشکل پروژه بدون مدارک خوانده ام-چگونه می توانید یک پروژه را ترویج کنید وقتی که هیچ کس نمی داند چه کاری انجام می دهد؟ بعد از خواندن آن ، این مقاله و راه حل مشابه آن را در همه جا دیدم. این راه حل توسعه محور README (RDD) است.
در پروژه های منبع آزاد و Innersource ، مانند آنهایی که در Github ، GitLab و Bitbucket پیدا می کنید ، سند Readme صفحه استقبال پروژه است. این اولین چیزی است که مردم هنگام جستجوی یک پروژه می بینند. اسناد Readme توصیف می کند که پروژه چیست ، چگونه از آن استفاده می کنید و چگونه می توانید به آن اضافه کنید. اگر می خواهید پروژه شما موفق باشد ، سند Readme شما باید اولین تصور خوبی را ارائه دهد.
در RDD ، هنگامی که یک پروژه جدید را شروع می کنید ، با پرونده Readme شروع می کنید. این باعث می شود قبل از شروع نوشتن هر کد ، پروژه خود را برنامه ریزی کنید. ابتدا با ایجاد README ، باید در مورد اینکه چرا پروژه را شروع کرده اید ، نحوه استفاده از آن و اینکه دیگران چگونه می توانند از آن پشتیبانی کنند ، فکر کنید. این پروژه شما را از ابتدا ساده تر می کند. RDD همچنین به این معنی است که پروژه شما با یک پایگاه مستندات محکم شروع می شود. به جای ایجاد مستندات خود پس از واقعیت ، شما با سندی شروع می کنید که با تکامل پروژه تکامل می یابد. این بسیار ساده تر از تلاش برای به یاد آوردن هر جزئیات اجرای پس از فشار پروژه تمام شده است.
نمودار زیر رویکرد کلی RDD را نشان می دهد.
در این مقاله ، من در مورد چگونگی مقایسه RDD با سایر استراتژی های “توسعه محرک” ، جوانب مثبت و منفی آن و تجربه خودم با آن بحث می کنم.
زمینه تاریخی توسعه محور README
دنیای توسعه نرم افزار بسیاری از استراتژی های “توسعه رانده شده” را مشاهده کرده است. برخی از نمونه ها عبارتند از: توسعه تست محور (TDD) ، طراحی یا توسعه مستند (DDD) و توسعه اشکال رانده شده (BDD). آنها طرز فکر را توصیف می کنند که توسعه دهندگان نرم افزار برای ایجاد محصولات خوب اتخاذ می کنند. غالباً ، آنها بر اهمیت یک مؤلفه چرخه توسعه ، مانند سوئیت های تست یا صید اشکال تأکید می کنند. این مؤلفه به نیروی محرکه تمام تلاش تبدیل می شود. این نوع استراتژی های توسعه نرم افزار در سنین بالا قرار گرفته است. من برای اولین بار در مورد یکی از آنها – توسعه محرک – در رابرت مارتین خوانده ام کد تمیز: یک کتابچه راهنمای نرم افزاری چابکبشر از آن زمان ، من انواع تغییرات را دیده ام.
چگونه RDD در این گروه از استراتژی های توسعه جای می گیرد؟ RDD به جای تست یا اشکالات ، روی مستندات یک پروژه تمرکز دارد. به طور خاص ، در مورد پروژه های منبع باز یا Innersource که مستندات خود را به عنوان صفحه فرود خود برای کاربران جدید دارند ، صدق می کند. RDD ، مانند انواع پروژه هایی که در آن ارائه می دهد ، فضای انعطاف پذیری را ترک می کند. RDD با مستندات – Readme – شروع می شود و با تکامل این پروژه به تکامل می یابد. به این ترتیب ، با روشهای دیگر استراتژی های “توسعه محرک” ، مانند چابک ، متناسب است.
جوانب مثبت و منفی توسعه محور README
RDD دارای قدرتهای زیادی است ، از جمله:
- این برنامه پروژه شما را بهبود می بخشد
- اگر قبل از نوشتن یک خط کد با README شروع کنید ، باید در مورد نحوه عملکرد پروژه خود فکر کنید. یک README آنچه را که پروژه شما انجام می دهد و نحوه اجرای آن را پوشش می دهد. اگر قبلاً برنامه ای برای اینها دارید ، نقشه راه برای نحوه ساخت کل پروژه دارید. در نتیجه ، شما یک پایگاه کد منسجم ایجاد می کنید که سریع یاد می گیرد و به راحتی قابل گسترش است.
- مشارکت دیگران را برای دیگران آسان می کند
- یک README واضح در را برای سایر توسعه دهندگان باز می کند تا به پروژه شما بیفزایند. اولین قدم برای مشارکت در هر پروژه یادگیری پایگاه کد است. فقط وقتی یک توسعه دهنده درک کند که چگونه قطعات پروژه در کنار هم قرار می گیرند ، می توانند پیشرفت هایی را ارائه دهند. اگر می خواهید مشارکت کنندگان بیشتری را به خود جلب کنید ، باید زمان مطالعه مورد نیاز را کاهش دهید. این جایی است که یک readme خوب نوشته شده کمک می کند. مستندات README شما نحوه عملکرد پروژه شما را توصیف می کند. اگر README شما پروژه را به زبان ساده توصیف می کند ، دیگران می توانند ببینند که چگونه و از کجا می توانند بدون حفر از طریق کد خام مشارکت کنند.
- این مستندات را به روز نگه می دارد
- نوشتن مستندات برای یک پروژه تمام شده سخت تر از به روزرسانی مستندات با رشد یک پروژه است. اگر پروژه خود را با یک سند README به خوبی نوشته شده شروع کنید ، می توانید آن را در طول مسیر به روز کنید. در غیر این صورت ، شما باید بعد از نوشتن کد ، تمام ساعتهای جزئیات پروژه یا بعضی اوقات روزها را به خاطر بسپارید. اغلب ، پروژه ها به هیچ وجه بدون اسناد و مدارک به پایان می رسند. RDD تضمین می کند که پروژه شما با یک بنیاد مستند و مستند آغاز می شود.
اگرچه RDD اشکالاتی دارد. با RDD ، به جای ساختن آن ، در مورد آنچه می خواهید بسازید می نویسید. شما خود را عقب نگه دارید – شما باید ابتدا readme را بنویسید. این یک عمل در تأخیر در رضایت است. بعضی اوقات ، این تأخیر به نظر نمی رسد که ارزش آن را داشته باشد. به عنوان مثال ، این پست توسط Lonestar Agile ادعا می کند که RDD ممکن است برای پروژه هایی که به سرعت تغییر می کنند نامناسب باشد. اگر یک پروژه کوچک یا بی ثبات را مدیریت می کنید ، ممکن است فکر کنید که RDD بار بیشتری را برای سود کمی اضافه می کند.
این البته یک مسئله جدی است. اما می توان با تمرین و آموزش غلبه کرد. توسعه دهندگان می آموزند که قرار دادن ایده های خود در کلمات به معنای کمتری در طول توسعه است ، بدون توجه به اندازه پروژه. آنها همچنین می آموزند که وقتی یک برنامه خشن برای شما ارائه شده است ، تجربه برنامه نویسی نرم تر است. و هر کس دیگری در چرخه توسعه از مستندات روشن بهره می برد.
تجربه توسعه رانده شده README من
بعد از خواندن درباره RDD ، فکر کردم که آن را برای یک پروژه کاری جدید امتحان می کنم. من می خواستم یک مخزن از نوت بوک های Databricks ایجاد کنم تا به کاربران فنی کمتری کمک کند تا داده های خود را در محیط خود بخواند و بنویسند. قبل از نوشتن یک خط کد ، من با Readme شروع کردم. این بسیار سخت تر از آنچه انتظار داشتم بود. همانطور که در مورد این ایده های عالی نوشتم و توسعه دادم ، می خواستم مستقیماً به درون آنها شیرجه بزنم. در عوض ، من خاموش شدم. خوشحالم که این کار را کردم. از آنجا که من با مستندات شروع کردم ، هدف این پروژه آسانتر بود. در یک مقطع ، من همه چیز را رها کردم و شروع کردم زیرا فهمیدم که مشکل اصلی را حل نمی کنم. من نیاز به محوری داشتم ، و وقتی که قبلاً وقت خود را برای تهیه کد هدر نداده اید ، بسیار ساده تر است.
آزمایش RDD من فایده دیگری داشت. این یک نقطه ورود آسانتر به پروژه به من داد. وقتی یک پروژه بزرگ را در ذهن دارید ، دشوار است بدانید که از کجا شروع کنید. با کدام اسکریپت شروع می کنید؟ چگونه پوشه های پروژه را ساختار می دهید؟ آیا این یک بسته است یا باید آن را به بسیاری تقسیم کنم؟ با یک readme ، دقیقاً می دانید از کجا شروع کنید: The Readme. این امر تمرکز و شروع کار را بسیار ساده تر کرده است.
پایان
ایده اصلی توسعه Redme Dreveloped نوشتن README ابتدا است. قبل از نوشتن یک خط کد ، آن را بنویسید. به این ترتیب می توانید پروژه خود را بهتر برنامه ریزی کنید ، پروژه خود را برای مشارکت کنندگان بیشتر باز کنید و اطمینان داشته باشید که پروژه شما در حال حاضر پایه و اساس خوبی در مستندات خود دارد.
اگر علاقه مند به یادگیری بیشتر هستید ، این منابع را بررسی کنید:
