اسناد کد، ساده – مجله Smashing

همه چیز پیرامون مستندات نرم افزاری دشوار است – از اختصاص زمان برای انجام آن تا به روز نگه داشتن آن. موفقیت در مستندسازی دشوار است و اغلب زمان کافی برای اندازه‌گیری تأثیر وجود ندارد. دلیل آن این است که آنها تأثیر ملموسی بر تجربه کاربر نهایی نمی گذارند. ما نمی توانیم برای اسناد بزرگ ارزش قائل شویم. به همین دلیل، به ندرت تلاش برای ایجاد و حفظ مستندات لذت بخش، بر سرمایه گذاری زمانی و برنامه ریزی مناسب اضافه وزن نمی گذارد.

پنی یا دایم

توسعه دهندگان نرم افزار در کار نوشتن کد و محتوا هستند (خوب، اکثر ما 😉). ما به راحتی می توانیم حقوق خود را در مقایسه با ویژگی هایی که ارسال می کنیم و درآمدی که از طریق آنها به دست می آید، توجیه کنیم. بنابراین، وقتی نوبت به نوشتن و آموزش همتایان خود در مورد آن ویژگی‌ها می‌شود، به طوری که آنها توانایی بیشتری در تعامل با کد خود دارند، ما اغلب ارزش آن دقیقه‌ها را در مخالفت با ارسال ویژگی بعدی یا رفع آن اشکال بد در همان جا زیر سوال می‌بریم. بدهی های فنی زیادی وجود دارد، پس چرا ما در مورد کدهایی می نویسیم که باید آن را اصلاح کنیم؟

ما بلافاصله آن دقایق را ذخیره می کنیم – این یک انتخاب واضح است. راست برگشت به کد. و ما فقط چند پنی از زمان خود را ذخیره کردیم. کمی به جلو حرکت کنید؛ یک همکار باید به آن بپرد و تغییری را اعمال کند. شما بیرون هستید (در حال کار روی چیز بزرگ بعدی، در یک جلسه، در تعطیلات، یا شاید شرکت را ترک کرده باشید!)، و هیچ سندی وجود ندارد. این سکه ها اکنون شروع به جمع آوری علاقه می کنند. خوشبختانه، چند نظر در کد وجود دارد. خوب است که بدانیم src در واقع یعنی source، و function sort(a, b) دو عدد صحیح می گیرد. اما دلیل واقعاً وجود ندارد، بنابراین بیایید به کند و کاو ادامه دهیم. درخواست کشش هیچ توضیحی ندارد، git blame کمکی نمی کند زیرا کسی که کد را نوشته است در اطراف نیست. حدس می‌زنم وقت آن است که کارآگاهی و مهندس معکوس بازی کنیم. آن سکه ها در حال حاضر سکه هستند. توصیف دارای اضافه بار شناختی بسیار کمتری نسبت به تحقیق است. بنابراین، هزینه توسعه برنامه ما با زمان توسعه دهنده، کار به کار افزایش می یابد.

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

مسواک زدن دندان ها

امیدواریم همه ما بتوانیم موافق باشیم که مسواک زدن دندان‌هایمان کاری است که باید هر روز انجام شود. این عادتی نیست که بتوانیم همه آن را در روز جمعه انجام دهیم و روزهایی که از دست داده ایم را جبران کنیم. و در این مورد، مستندات به نوعی مشابه است. البته، ما می‌توانیم همه آن را تا پایان سه‌ماهه بنویسیم، اما بسیار سخت‌تر و زمان‌برتر خواهد بود. به عنوان مثال: آیا به یاد دارید که چه چیزی (یا چرا!) را سه ماه پیش کدنویسی کردید؟

بار شناختی بیش از حد مستند کردن چیزها از زمانی که کد را ارسال می کنید افزایش می یابد. در حالت ایده آل، مستندسازی مانند تست نوشتن است (که همه ما انجام می دهیم!) و هر بار که چیزی را تغییر می دهیم، اسناد را به روز می کنیم.

موانع را بردارید

متأسفانه، بسیاری از ما عادت به نوشتن مستندات را ایجاد نمی کنیم – این به این دلیل است که گردش کار اغلب پر از اصطکاک است. ما کد را تمام می کنیم، فایل (یا IDE یا پروژه) را می بندیم و به ویرایشگر Markdown (یا Jira یا Wiki و غیره) می پریم و اکنون باید مکان مناسبی را برای قرار دادن دانش خود پیدا کنیم. به تازگی ایجاد کرده‌اید، آن را برای بررسی ارسال کنید – دیگران به ما خواهند گفت که آیا بهترین نقطه را انتخاب کرده‌ایم، اگر آن را به اندازه کافی واضح نوشته‌ایم، و غیره. (اگر شما هستید، سخت است! آنجا بودم، این کار را انجام دادم. شما همدردی من را دارید.)

همانطور که روند ادامه می یابد، تصمیمات سوالاتی را ایجاد می کنند. و بله، تمرین عالی می‌شود – اما در حالت ایده‌آل، ما نیازی به صرف چنین مقدار زیادی زمان (و انرژی!) برای انجام بررسی لازم نداریم. این اصطکاک در حفظ این عادت بر علیه ما کار می کند و زمانی که برای یافتن نقطه ای برای قرار دادن کد صرف کرده ایم انگیزه ما را تخلیه کرده است.

قطعات متحرک را به هم وصل کنید

طبق معمول، راه حل توسعه دهنده برای یک مشکل اصطکاک است اتوماسیون. با مشتق کردن آنها از کارهای خسته کننده و تکراری فرار کنید. شنا کن این کار را با گرفتن چند مورد از آن تصمیمات متعدد برای شما در چیزی که آنها “اکوسیستم مستندسازی” می نامند انجام می دهد – یک نامگذاری بسیار مناسب.

1. مدارک را کجا قرار دهیم؟ همانجا، با کد.
2. چه زمانی باید مستندات را بنویسیم؟ همانطور که آن را اجرا می کنید. یا زمانی که PR را باز می کنید (حداکثر!).

به طور خلاصه، شما یک روش می نویسید. شما همونجا روش رو توضیح میدین بخش “جادویی” زمانی به وجود می آید که، به دلیل اینکه آنها در کنار هم قرار می گیرند، امکان مستندسازی مستقیم پارامترها و متغیرها وجود دارد. در کد به متن موجود در اسناد به این ترتیب، وقتی کد تغییر می‌کند، اسناد می‌دانند که منسوخ شده‌اند و می‌توانند کل تیم شما را در مورد آن پرچم‌گذاری کنند.

تمام این اتوماسیون منظم نیاز به تنظیم کمی و احتمالاً چند تغییر در رابط های کدنویسی و فرآیندهای مرتبط دارد.

کد به Docs

اگر از کد VS یا یکی از IDE های JetBrains استفاده می کنید، امکان ادغام افزونه/افزونه وجود دارد. پس از نوشتن کد، یک “موج شنا” در کنار کدی که از قبل مستند شده است ظاهر می شود، بنابراین می توانید پیوند را دنبال کرده و کد را در یک ویرایشگر Markdown پیشرفته ویرایش کنید. این ویرایشگر چند تکمیل خودکار جالب از کد شما دارد (شروع به تایپ نام متغیر کنید و خواهید دید که تکمیل خودکار می شود). تا آنجا که ممکن است از آن استفاده کنید زیرا این مکانیزم برای پیوند کد شما به اسناد شما است.

نسخه به اسناد

با GitHub، هنگامی که مستندات با کد همراه می‌شوند، بررسی نیز در همان روابط عمومی انجام می‌شود. ربات ادغام قادر به شناسایی است توکن های هوشمند در سراسر کد تغییر کرده و تنظیماتی را که قبلاً انجام شده است (که از قبل بازبینی می شود) یا موارد دست نخورده (همچنین درخواست بازبینی) را علامت گذاری می کند. با نظرات فردی که بیشتر شبیه درخواست‌های روابط عمومی هستند، بازبینان روابط عمومی شما می‌توانند هر بخش نظر را یکی یکی تأیید کنند، بسته به اینکه چقدر با آنها راحت هستند.

علاوه بر این، با بررسی‌های خودکار (همگام‌سازی خودکار ثبت اختراع Swimm)، می‌توان تأییدیه‌ها و راه‌اندازهای اعلان‌های خودکار را تنظیم کرد یا آنها را به‌طور کامل بی‌صدا کرد. بنابراین تیم شما می تواند از اضافه بار اعلان جلوگیری کند و نحوه آگاهی آنها از تغییرات را به گونه ای تنظیم کند که برای آنها مناسب است.

آن را از اینجا بگیرید

امیدوارم این نگاه اجمالی به مشکل نوشتن مستندات به نحوی با شما طنین انداز شده باشد و ایده های اطراف اینجا منطقی باشد. لطفا در نظرات زیر تماس بگیرید یا به من پاسخ دهید @AtilaFassina اگر چیزی وجود دارد که می خواهید اضافه کنید یا فقط درباره اسناد عالی گپ بزنید. من عاشق یک داستان موفقیت خوب هستم!

(vf, il)