مستندسازی
این فصل پوشش میدهد
- دلیلهای اهمیت مستندسازی
- انواع مختلف مستندات
- قدرت نمودارها و ترسیمها در برقراری ارتباط
- راهبردهایی برای بافتن مستندسازی در فرایند فعلی شما
میدانید این فصل قرار نیست چیزی به شما بگوید که از قبل نمیدانید؛ ما فناورها در یک حوزه بهشدت شکست میخوریم و آن مستندسازی است. بهندرت شرکتی را میبینید که مستندات کافی داشته باشد. همه پر از نیتهای خوباند، اما چیزی نوشته نشده است. مستندسازی مثل مورد آزمون است: هیچوقت زیادی نیست. اما سطح درست آن چیست؟ از کجا میفهمید مقدار درستی دارید؟ در این فصل، حوزههایی را برجسته میکنیم که دستکم به سطحی اجمالی از مستندسازی نیاز دارند و حوزههایی را که جزئیات عمیقتری میخواهند، از جمله حوزههایی که برای اجرای روان و تداوم تیم شما حیاتیاند. هرچند این فهرست به هیچ وجه کامل نیست، نقطه شروعی است تا درباره انواع مستنداتی فکر کنید که باید برای پشتیبانی از سیستمهای نیرودهنده سازمانتان، فراتر از عمر کاری هر عضو تیم، در نظر بگیرید. مستندسازی از آن چیزهایی است که اگر همراه مسیر بهروز نگه داشته شود، تا حدی خودش از خودش مراقبت میکند. اما اگر رها شود، خیلی زود به کاری عظیم تبدیل میشود.
۱۱.۱ چرا مستند کنیم؟
اصلا چرا زحمت بکشیم؟ تیم شما میداند چیزها چگونه کار میکنند، مثل داستانهای باستانی که از نسلی به نسل بعد منتقل میشود. علاوه بر آن، استک شما آنقدر خوب طراحی و نگهداری شده که هر فرد شایستهای میتواند آن را بفهمد. اگر چنین باوری دارید، احتمالا باور دارید کدتان هیچ باگی ندارد و در نتیجه نیازی به تست ندارد! وقتی اینطور روی کاغذ میآید نامعقول است، اما بسیاری صادقانه به آن باور دارند. مستندسازی تداوم است. مستندسازی مقیاسپذیری است. مستندسازی آزادی است. نشانه ضعف یا کار اداریای نیست که باید تحمل شود و تا آخرین دقیقه عقب بیفتد. معماری شما هرقدر مدرن و کدتان هرقدر خوانا باشد، سطحی از قواعد و منطق وجود دارد که فقط برای سازمان شما معنا دارد. این همان جزئیات است؛ دلیلهای پشت تصمیمهای طراحی که خواندن کد هرگز بهطور کامل توضیحشان نمیدهد. مستندسازی دفترچه راهنمای عملیاتی سازمان شماست و بدون آن، هیچکس نمیتواند از مزایای سازمان شما بهطور کامل بهره ببرد.
انسانها جزئیات را فراموش میکنند. روزها به هفته، هفتهها به ماه و ماهها به سال تبدیل میشوند و دلیل اینکه چیزی چرا به آن شکل انجام شده گم میشود. یک قاعده کسبوکار عجیب یا محدودیت مبهم که در زمان خود طراحی یا پیادهسازی را به مسیری مشخص برده بود، و آن زمان تصمیم درستی هم بود، ممکن است در آینده چندان آشکار نباشد. وقتی دلیلها در مه زمان گم میشوند، یکی از دو اتفاق میافتد:
- فرد تازهای آن را میبیند، فکر میکند راه سادهتری وجود دارد، تغییرش میدهد و در فرایند، چیزی را خراب میکند.
- افراد میترسند به آن دست بزنند یا حتی به بازسازیاش فکر کنند. آن بخش ویژگی افسانهای پیدا میکند و آنقدر پیچیده یا حیاتی دیده میشود که هر تغییری در آن پرریسک به نظر میرسد.
هر دو سناریو ریسک بسیار زیادی وارد میکنند، در حالی که هر دو میتوانستند با کمی مستندات در اطراف سیستم، برای توضیح اینکه چه میگذرد، کاملا اجتناب شوند. همانطور که یک توسعهدهنده دانا زمانی گفت: «کامنتهای کد یادداشتهای کوچک عاشقانه برای خود آینده شما هستند.»
۱۱.۱.۱ مخاطب
مستندسازی موجودیتی واحد نیست که بتواند نیاز هر خوانندهای را برآورده کند. مجموعهای از اسناد است که بسته به نحوه تعامل افراد با سیستم، برای گروه مشخصی از گیرندگان نوشته میشود. برای فکر کردن به این انواع مختلف، این تقسیمبندی را در نظر بگیرید:
- کاربر نهایی: کاربران سیستم که با محصول نهایی تعامل دارند
- پشتیبانی: پشتیبانی خط مقدم که به پرسشهای کاربران نهایی کمک میکند
- IT/DevOps: تیم پشتی که مسئول روشن و عملیاتی نگه داشتن سیستمهاست
- توسعهدهندگان: تیمی که ویژگیها را میسازد یا اصلاح میکند
با رشد و پیر شدن سیستمها، نیازهای مشخص هر مخاطب شروع به گسترش میکند. تیمهای کوچک در آغاز مسیر کارآفرینی ممکن است همپوشانی زیادی داشته باشند، نقشها توسط همان افراد انجام شود و شاید برای کاربر نهایی اصلا مستنداتی وجود نداشته باشد. با رشد کار، هر مخاطب جریان فرایندی و مسئولیت خود را خواهد داشت که از لایه پایینتر به پشتیبانی و مستندات نیاز دارد. داشتن منبع خوب اطلاعات تضمین میکند هر مخاطب، از کاربر نهایی تا توسعهدهنده، بتواند افراد جدید را سریع و کارآمد آمادهسازی کند و به آنها امکان دهد در نقش خود کاملا موفق شوند. زمینهمند کردن مستندات برای هر نوع مخاطب، بهگونهای که با واژگان و سبک زبان خودشان صحبت کند، کمک را دسترسپذیرتر میکند. برای مثال، توضیح الگوریتمها برای کاربر نهایی یا نیروی پشتیبانی معنای زیادی ندارد، اما به توسعهدهندگان در نگهداری و سازگار کردن نرمافزار کمک میکند. به همین ترتیب، راهنمای گامبهگام همراه با مجموعهای از تصویرهای صفحه به تیم IT/DevOps کمک چندانی نمیکند، چون برایشان مهم نیست برنامه چه شکلی است؛ آنها فقط میخواهند بدانند چیزها، مثلا پشتیبانگیریها، چگونه مدیریت میشوند. با مخاطب صحبت کنید.
۱۱.۱.۲ قالب
وقتی به مستندسازی فکر میکنیم، معمولا به قالب کلاسیک متن متمایل میشویم: بهراحتی ساخته میشود، روشن است، ذخیره، حمل، ارجاع و جستوجو میشود. با این حال، ویدئوها روزبهروز محبوبتر میشوند، بهویژه ویدئوهایی که عملا جلسه دسکتاپ را ضبط میکنند، انگار از پشت شانه کسی نگاه میکنید که نشان میدهد کاری چگونه انجام میشود. با دسترسی گسترده به ابزارهای ساخت و ویرایش ویدئوهای کوتاه، ضبط و اشتراک یا انتشار آنها میتواند سریع باشد؛ یک ویدئوی پنجدقیقهای ممکن است معادل چند صفحه متن توصیفی سنتی باشد.
راهبرد موفق مستندسازی باید در زمان نیاز قابل دسترس و موجود باشد. هرقدر یک قطعه خوب باشد، اگر هنگام نیاز پیدا نشود، تقریبا بیفایده است. قفل کردن مستندات در فایلهای PDF یا DOC، هرچند ۲۰ سال پیش عالی بود، دیگر روش اصلی نیست. یک سند، بهویژه سندی که هدفش توصیف یا آموزش درباره پلتفرم است، موجودیتی زنده و پویاست. باید با هر انتشار یا هر کشف تازه بهروز شود. این کار باید سریع، آسان و بیزحمت باشد و خودش به پروژهای جداگانه تبدیل نشود. وقتی Tim Berners-Lee نخستین بار وب را مطرح کرد، هدفش اشتراک آسان اطلاعات بود. پس منطقی است که وب نقطه کانونی یک مخزن اسناد باشد. ابزارهایی مثل ویکیها، Atlassian Confluence، Google Docs و Office 365 همگی گزینههای خوب درون مرورگرند. هنگام ارزیابی راهکارهای پلتفرم مستندسازی، این موارد را در نظر بگیرید:
- لینک مستقیم به محتوای مشخص: مطمئن شوید میتوانید کسی را بدون دادن چند مرحله ناوبری، مستقیم به بخش مشخص بفرستید.
- سازماندهی محتوای مرتبط: باید جمع کردن حوزههای مرتبط آسان باشد تا خواننده بتواند محتوای عمیقتر را پیدا کند. ایدهآل آن است که این کار از طریق برچسبها یا هوش معنایی خودکار انجام شود.
- افزایشپذیری آسان: وقتی اطلاعات تازه روشن میشود، محتوا باید بهروز شود، بهویژه برای پشتیبانی.
- نسخهپذیری: بیشتر ابزارهای مدرن این کار را بهصورت پیشفرض خیلی خوب انجام میدهند. امکان برگشت سریع به نسخه قبلی باعث میشود اسناد باوقار پیر شوند و رشد کنند، و خواننده هم بتواند تشخیص دهد چیزی که مصرف میکند به نسخهای که با آن کار میکند مرتبط است یا نه.
- امنیت: همه چیز نباید برای همه قابل دسترس باشد، پس به توانایی حفاظت از حوزهها یا بخشهای مختلف برای گروههای متفاوت نیاز دارید.
- بازخورد: خوانندگان باید بتوانند کامنت یا یادداشتهای کوچک بگذارند تا محتوا را غنیتر کنند.
- پیوستها: امکان افزودن فایلهای شخص ثالث، مثل تصویر، ویدئو یا PDF، چقدر سازگارپذیر است؟ میخواهید این داده نزدیک سندی بماند که به آن مربوط است.
محتوای خوب لازم نیست زیبا به نظر برسد؛ فقط باید به خواننده کمک کند. تشویق همه برای مشارکت در این پایگاه دانش در حال شکلگیری، برای موفقیت و سودمندی آن حیاتی است. هرچه اصطکاک در نوشتن و مشارکت کمتر باشد، بهتر است.
۱۱.۱.۳ اعتبارسنجی
ما با نیاز به تست کردن کد پیش از انتشار آشناییم؛ چه تست خودکار باشد و چه، رایجتر، تست دستی برای تایید اینکه کد کاری را میکند که باید بکند. همانطور که میدانیم، «فرض کردن» اینکه همه چیز خوب خواهد بود راه اداره یک پلتفرم فناوری مدرن نیست. همین موضوع درباره هر مستندی که تولید میشود نیز صادق است. پیش از آنکه سند توسط مخاطبش خوانده و مصرف شود، باید اعتبارسنجی شود که اصلا ارزش تولید داشته است. هر قطعه مستند، بهویژه در روزهای ابتدایی پیدایش، باید توسط کسی غیر از نویسنده اعتبارسنجی شود تا مفید بودن آن تایید شود و مطمئن شوید درباره مصرفکننده و موضوع، فرضهای بیش از حد یا حذفهای زیادی نداشته است.
لازم نیست فرایند رسمی بازبینی سند باشد، اما باید یک جفت چشم دوم را شامل شود. برای مثال، فرایند ساخت برای تولید، اعتبارسنجی و انتشار پلتفرم را در نظر بگیرید. به جای اینکه فقط در سر فرد سازنده فرایند بماند، آن فرد مستندش میکند. از کجا میدانید به اندازه کافی کامل است؟ باید تست شود؛ کسی آن را اجرا کند، ایدهآل این است که فردی باشد که خیلی با موضوع آشنا نیست و ناخودآگاه از شکافها عبور نمیکند. این آزمون خوبی برای سنجیدن پایداری محتواست. حوزههایی که معمولا توسط یک نفر انجام میشوند همان جاهاییاند که باید توجه ویژهای به آنها داشته باشید: آیا همه کارهایی که انجام میدهند آنقدر ثبت شده که هر کسی بتواند نقش را پشتیبانی کند؟ فقط با تست کردن مستندات میتوانید با اطمینان به این پرسش پاسخ دهید.
۱۱.۲ انواع مستندات
در این بخش، انواع معمول اسنادی را مرور میکنیم که شما بهعنوان سازمان باید در کتابخانه خود داشته باشید یا دستکم در نظر بگیرید. این فهرست به هیچ وجه کامل نیست، اما اگر نمیدانید از کجا شروع کنید، نقطه شروعی است.
۱۱.۲.۱ یادداشتهای جلسه
جلسهها باید رویدادهایی کمتعداد باشند، چون میتوانند حواسپرتی بزرگی ایجاد کنند و زمان زیادی بگیرند. وقتی تصمیم میگیرید جلسه لازم دارید، باید تا حد ممکن پربازده باشد. جلسه خوب جلسهای است که یک یا چند هدف یا دستورکار با نتیجهای هدفمحور داشته باشد. جلسهها میتوانند منبع بزرگی برای تبادل اطلاعات، ایدهها و پیشنهادهای فراوان باشند. با این حال، اغلب جایی هستند که یادداشت کمی برداشته میشود یا اصلا برداشته نمیشود، و در نتیجه اطلاعات ارزشمند زیادی از دست میرود؛ چه اتلافی. یادداشتهای جلسه باید بخشی از پایگاه دانش اصلی باشند و تاریخچه تصمیمها را تا رسیدن به نقطهای مشخص توضیح دهند. برخی سازمانها «ثبت تصمیم» جداگانهای نگه میدارند؛ جایی واحد که توضیح میدهد چرا برخی تصمیمهای بزرگ گرفته شدهاند. برای هر جلسه، کسی را برای یادداشتبرداری تعیین کنید و در زمان جلسه، وقت لازم برای آماده کردن یادداشتهای جلسه را بگنجانید. برخی افراد در لحظه در Google Doc یادداشت نگه میدارند و لحظهها و تصمیمهای کلیدی را ثبت میکنند. اگر جلسه سریعی برای یک تیکت خاص برگزار شده، در کامنتهای همان تیکت چند نکته گلولهای ایجاد کنید و خروجی جلسه را ثبت کنید. با توجه به جهان پساکرونا، بسیاری از جلسهها از طریق ویدئو آنلاین شدهاند. زمان خوبی است که جلسههای کلیدی را ضبط کنید و کتابخانهای از آنها نگه دارید تا تصمیمهای حیاتی از دست نروند.
۱۱.۲.۲ گفتوگوهای چت
تبادلها در چت، مثل Slack، Microsoft Teams و مانند آن، نیز میتوانند گوهرهای دانشی داشته باشند. تیم خود را تشویق کنید برخی از این موارد را کپی و جایگذاری کنند تا به پایگاه دانش اصلی یا تیکت اضافه شود. حتی میتوانید باتها یا افزونههایی پیدا کنید که برچسب کردن یک گفتوگو و ارسال آن به مخزن دوردست را سریع میکنند.
دموها و مرورهای گامبهگام
به تعداد دفعاتی فکر کنید که یک دموی محصول یا مرور گامبهگام انجام میشود. چند مورد از آنها ضبط شدهاند؟ هر چند بار هم که اجرا شوند، هر تکرار چیز تازهای به همراه دارد؛ شاید پرسشی جدید یا متفاوت از مخاطب، یا اتفاقی خاص که رخ داده است. دیدن دموهای فروش از محصول اصلی خوب است، چون میبینید تیم فروش چگونه ویژگیها را ارائه میکند و کشف میکنید مشتری یا کاربر ویژگی را چگونه درک میکند و از آن چه میخواهد. میان این دو گروه ممکن است فاصله زیادی وجود داشته باشد. نگه داشتن این ضبطها به گروه محصول کمک میکند بفهمد کاربران چه نیاز دارند، به گروه مهندسی کمک میکند بفهمد چه چیز مهم است، و در نهایت به اعضای تازه تیم کمک میکند بفهمند در ساخت چه چیزی نقش دارند. اینها در طول زمان انباشته میشوند؛ اما از حجم نترسید. اثر جانبی زیبایی هم دارد: مثل کپسول زمان برای نسخههای تاریخی است، برای کسانی که وارد شرکت میشوند و با مصرف آنها یاد میگیرند تکامل چگونه محیط را شکل داده است.
راهنمای مالک
احتمالا یکی از مهمترین حوزههای مستندسازی، حوزهای است که توضیح میدهد چگونه سازمان را روشن و در حال اجرا نگه دارید؛ اگر بخواهیم نامی بدهیم، راهنمای مالک. این مستند، استقرار کد نیست. بلکه همه قطعههای پلتفرم و نحوه عملکرد آنها، نحوه پایش آنها و کاری است که باید انجام شود تا در صورت قطعی برق یا رویداد آفلاین دیگر دوباره آنلاین شوند. سطح جزئیات اینجا باید آنقدر کافی باشد که هر کسی بتواند وارد شود و رویه را اجرا کند. صرف گفتن اینکه «مطمئن شوید جزء XYZ را راهاندازی دوباره میکنید» کافی نیست. جزء XYZ را چگونه راهاندازی دوباره میکنید، چه دستورهایی باید از کجا اجرا شوند، برای تعیین موفقیت دنبال چه چیزی باید باشید و برای اصلاح مشکلاتی که پیش میآید چه گامهایی لازم است؟ بخش زیادی از این جزئیات اغلب نادیده گرفته میشود و بخشی از حافظه عضلانی یک نفر است. مثلا راهاندازی یک سیستم ممکن است خروجی کنسول زیادی تولید کند. فردی که به دیدن این خطهای لاگ عادت ندارد ممکن است در ابتدا گیج شود و نداند چه چیزی خوب است، چه چیزی بد است و چه چیزی را باید نادیده گرفت. یک تصویر صفحه ساده از این خروجی در مستندات میتواند اضطراب زیادی را کاهش دهد و سطح اعتماد را بالا ببرد. مثل ضربالمثل قدیمی، یک تصویر به اندازه هزار کلمه ارزش دارد.
راهنمای مالک لازم نیست پرحرف باشد. قرار نیست کتاب بعدی Harry Potter را بنویسید. شما گامهای دقیق درباره کارهایی میدهید که باید تکمیل شوند. ساده نگه دارید: فهرستی از گامهای شمارهدار که هرکدام آنقدر روشن باشد که خواننده وضوح و اعتماد داشته باشد که بداند چه زمانی آن گام با موفقیت کامل شده و میتواند به گام بعدی برود. این حوزه همچنین باید مراقبت از سیستمهای در حال اجرا را پوشش دهد: نشانههای اولیهای که باید مراقبشان باشید و میتوانند سرنخی از مشکل قریبالوقوع بدهند چیست؟ ساختن این بخش در ابتدا میتواند دلهرهآور باشد. نکته کوچکی این است که از فرد اصلیای که سیستم مشخصی را مدیریت میکند بخواهید وانمود کند به تعطیلات میرود و ایمیلی برای فردی بنویسد که در غیاب او مراقب سیستم است. ایمیل کمتر رسمی است و افراد در ایمیل نسبت به صفحه خالی ویکی یا Google Doc معمولا پرحرفترند. این ایمیل را بگیرید و به پایگاه دانش اضافه کنید. این تمرین بارها جواب میدهد و در طول زمان کتابخانهای غنی و عمیق از راهنماهای عملی میسازد.
هیچکس در تیم شما نباید احساس کند تنها دلیل داشتن نقش در تیم، دانش داخلی او درباره یک سیستم مشخص است. این نگرش ۱۰ تا ۲۰ سال پیش نسبتا رایج بود، اما امروز کمتر با آن برخورد میکنم. ارزش و امنیت شغلی افراد در چیزی نیست که فقط میدانند، بلکه در چیزی است که به تیم اضافه میکنند. همه عاشق کار روی چیز تازه و براقاند؛ ما فناوریم و در DNA ماست که دنبال بهترین چیز بعدی بگردیم. مهم است سیستمهای فعلی تا حدی مستند شوند که هیچکس احساس نکند چون تنها کسی است که یک سیستم مشخص را میشناسد، پشت جا مانده است.
۱۱.۲.۴ پشتیبانگیری و بازیابی
حوزهای که در بخش مستندسازی اغلب کمتر خدمت میگیرد، پشتیبانگیری و بازیابی یک سیستم است. این فراتر از مسیر برونبری/درونریزی پایگاه داده است، هرچند آن هم باید جزئی شود. موضوع، کل سازمان است؛ از سختافزار تا سیستمعامل تا نرمافزار، همه چیز. برای دمیدن دوباره زندگی به یک جزء چه لازم است؟ چه بخشهایی از یک سیستمعامل باید موجود باشند تا آن جزء اجرا شود؟ چیزی که امروز بدیهی به نظر میرسد ممکن است ماهها یا سالها بعد همان معنا را ندهد.
باید به اندازه کافی یادداشت و راهنمایی وجود داشته باشد که هر فرد فنی شایستهای بتواند هر جزء سازمان را از کنترل منبع بازسازی کند. اگر این دستیافتنی نیست، شما در بدهی مستندات هستید. بهروز نگه داشتن طبیعی این موضوع باید بخشی از فرایند انتشار باشد، همانطور که اجزای تازه معرفی میشوند و اجزای legacy قدیمی جایگزین و حذف میشوند. همانطور که پیشتر اشاره کردهام، این حوزه دیگری است که باید دستکم سالی یکبار، اگر نه بیشتر، تمرین شود. اگر در محیط ابری اجرا میکنید، مدیریت آن بدون دخالت در محیط زنده یا به خطر انداختن آن بسیار ساده است. تمرین خوبی این است که افراد تازهاستخدامشده این فرایند بازیابی را در محیطی تمیز اجرا کنند. این تمرین راهی مرتب برای آشنا کردن افراد با فرایند است، در حالی که یاد میگیرند همه چیز چگونه کنار هم قرار میگیرد و مطمئن میشوید مستندات مرتبطاند.
فرایند استقرار
انتشار و بهروزرسانی سازمان باید مسیری بارها پیمودهشده، قابل پیشبینی و بیخطر باشد. برای اینکه چنین شود، به ابزارها و مستندات خوب برای پشتیبانی از این تلاش نیاز دارید. حتی اگر به ابزار ارکستراسیون خودکار، مثل Jenkins، تکیه میکنید، همچنان راهنمایی درباره اینکه برای محیط شما چگونه پیکربندی شده لازم است. همه گامهای لازم برای آماده کردن ساخت باید چیده شود، همراه با توضیح اینکه چه اتفاقی میافتد، معیار موفقیت چیست و شکست چگونه تشخیص داده میشود. سپس وقتی همه اینها کنار هم قرار میگیرند، باید در چه ترتیبی اجرا شوند و در چه نقطهای میتوانید پیش از ایجاد تغییر در محیط لغو کنید؟ اگر برای انتشار وصله، اصلاح فوری یا انتشار کامل فرایند متفاوتی دارید، اینها نیز باید جزئی شوند. مستندسازی موفق این گامها همه را آگاه نگه میدارد و مطمئن میشود انتشارها هرگز روی یک نفر گلوگاه نمیشوند. کم نیست شرکتی که توانایی بهروزرسانیاش به فرد ارشد DevOps وابسته است؛ البته وقتی در مرخصی نیست.
کامنتهای منبع/کد
اگر میخواهید بحثی میان توسعهدهندگان روشن کنید که همسطح معمای افسانهای «تب در برابر فاصله» باشد، که برای ثبت در تاریخ، پاسخ فاصله است، بپرسید چه تعداد کامنت باید در کد باشد. پاسخها از «کد من به کامنت نیاز ندارد، خودش خواناست» تا «بله، باز کردن این گره واقعا دردسر است» خواهد بود. دو حوزه اصلی که به توضیح بیشتری نسبت به آنچه صرفا از نگاه به کد منبع برداشت میشود نیاز دارند، «چه» و «چگونه» هستند. به میزان کمتر، «چرا» نیز باید ثبت شود، اگر آشکار نیست.
«چه»
این سطح جزئیات برای خوانده شدن توسط توسعهدهندگان دیگری طراحی شده که از آن قطعه کد استفاده میکنند. کتابخانهای با تابعها یا متدهای عمومی را در نظر بگیرید که توسعهدهندگان دیگر برای سیستمهای دیگر مصرف خواهند کرد. این میتواند نقطههای پایانی API را هم شامل شود که از راه دور مصرف میشوند. بیشتر زبانهای مدرن قرارداد یا زبان متاای دارند که میتواند کامنتهای سطح تابع را به سند کتابخانه تبدیل کند. این به توسعهدهندگانی که کتابخانه را وارد کردهاند اجازه میدهد این کمک کدی را از طریق سازوکار تکمیل کد در IDE خود ببینند.
Java نمونه خوبی است، با استاندارد Javadoc برای مستندسازی سطح کلاس و متد، که نهتنها برای تکمیل کد بلکه برای تولید مجموعهای از صفحات وب با مستندات کد استفاده میشود. نمونه دیگر کتابخانه Swagger برای مستندسازی نقطههای پایانی API در قالب HTML است، همراه با ابزاری برای فراخوانی دوردست نقطه پایانی جهت تست و تحقیق. مزیت بزرگ این مستندات این است که در همان فایل منبع کنار کد نگه داشته میشود و همین بهروز نگه داشتن آن را هنگام تکامل کد آسان میکند. این نوع مستندسازی حیاتی است، بهویژه برای تیمهای بزرگ یا زمانهایی که طرفهای بیرونی APIها را مصرف خواهند کرد.
«چگونه»
نوع دیگر مستندسازی درون تابعها و متدهای کد منبع قرار دارد و فقط برای توسعهدهندگان دیگری طراحی شده که همان کد را نگهداری میکنند. برای این سطح، جزئیات بیش از حد را توصیه نکنید. کدی که خوب طراحی و نوشته شده باشد باید برای خواننده آشکار باشد؛ با فرض نامهای معقول تابع و متغیر که با کاری که انجام میدهند مرتبطاند. کد باید برای خوانایی نوشته شود، نه عملکرد. با این حال، اگر یک بلوک کد به توضیح کمی بیشتر نیاز دارد، باید چند خط کامنت همراه داشته باشد. ایدهآل این است که لینکهای وب به شماره تیکت گذاشته شود تا به توسعهدهنده آینده عمق بیشتری درباره چرایی رفتار یک جزء بدهد. آن عبارت if عجیبوغریب میتواند با شماره تیکت توضیح داده شود، به جای اینکه توسعهدهندههای آینده فکر کنند با بازآرایی کردن آن به همه لطف میکنند و احتمالا بیش از باگهایی که حل میکنند، باگ وارد میکنند. مطمئن شوید مستندسازی کافی منبع در بازبینی کدها گنجانده میشود. وقتی توسعهدهندگان به این عادت برسند، دیگر به عقب نگاه نمیکنند.
«چرا»
اگر چیزی در بخش «چگونه» قابل انتقال نیست، باید به حوزه «چرا» ارتقا داده شود؛ جایی که معمولا در سطح کسبوکاری بالاتری توضیح میدهد تابع یا حوزه مورد نظر تلاش دارد چه کند. آیا قاعده کسبوکار یا شیوه خاص عملکرد یک شخص ثالث وجود دارد که تصمیم طراحیای را تحمیل کرده که در ابتدا آشکار نیست؟
۱۱.۲.۷ نمودارهای معماری
وقتی جعبهای شکلات گرانقیمت میگیرید، نخست دنبال چه میگردید؟ نقشه، البته! این نمایش چیدمان جعبه به شما فرصتی میدهد از فندقی که داخلش پنهان شده دوری کنید. شکلاتشناسهای واقعی از این نقشه استفاده میکنند تا سفر مزهای پیش روی خود را برای بیشینه کردن تزریق طعم طراحی کنند. نقشه به ما اجازه میدهد با اقتدار و اعتماد بیشتری حرکت کنیم. سازمان نیز باید همین «نقشه» یا نمودار معماری را داشته باشد. وقتی با سیستمی آشنا میشوید، همیشه بخواهید نقشه روی تخته سفید کشیده شود. اگر هنوز نگاههای خالی و پرسشگر گرفتید، فقط بگویید: «چند جعبه با خط بکشید.»
لازم نیست پیچیده یا رسمی باشد. اینها نقشههای فنی ساختمانی نیستند که از پروتکلهای سختگیرانه نقشهبردار پیروی کنند. فقط راهنماهاییاند که روایت توصیفکننده پلتفرم را قاب میگیرند. باید اجزای اصلی سازمان را شامل شوند، با خطهایی که قطعههای متصل را به هم وصل میکنند. در این سطح وارد جزئیات لجستیکی زیادی نشوید. همین کافی است که بدانید میکروسرویس فایل توسط ماژول عکسهای پروفایل کاربر استفاده میشود. «چگونه» در این سطح مهم نیست؛ ممکن است فراخوانی API باشد، صف باشد یا حتی دایرکتوری مشترک. آن جزئیات برای سند دیگری است. اینجا، اگر به قیاس نقشه برگردیم، مرزهای ایالتی را با بزرگراههای بینایالتی علامت میزنید تا اتصالها را نشان دهید، و فقط شهرهای بزرگ را به عنوان جزئیات میآورید. بیش از حد جزئی نشوید، چون نقشه شلوغ و سختفهم میشود.
برای هر جزء، یا هر ایالت در نقشه ما، نقشه جداگانهای ارائه میکنید و جزئیات بیشتری را کاوش میکنید، مثل نشان دادن بزرگراههای روستایی و شهرهای کوچک. قیاس نقشه بهویژه برای معماریهای میکروسرویس و API محور خوب کار میکند. مانند ایالتهای آمریکا، شهرها و بزرگراهها تغییر نمیکنند، اما راههای محلی داخل هر ایالت و شهر پیوسته تکامل مییابند. وقتی به نقشههای معماری خود با دقت فکر کنید، میتوانید رندرهایی بیابید که حتی سالها پس از تکامل کد هنوز مرتبطاند. نقشه سطح بالا باید چیزی باشد که بتوان از آن برای ارتباط دادن چیدمان به دیگران بیرون از گروه شما استفاده کرد، بیآنکه افراد در جزئیات یا اصطلاحات پیچیده غرق شوند. تعجب نکنید اگر به دک هیئتمدیره راه پیدا کند، چون یک نمودار خوب راهی عالی برای فروختن چشمانداز شماست.
نمودارهای فرایند
نمودار فرایند به نمودار معماری نزدیک است. این نمایش میدهد داده چگونه در سیستم جریان دارد و هنگام عبور از یک سرویس یا کتابخانه چه اتفاقی برای آن میافتد. اگر نمودار معماری نقشه ایالت یا بزرگراههای بینایالتی باشد، این یکی لایه Google جریان ترافیک است که نشان میدهد خودروها کجا هستند. نمودار فرایند جریان منطقی خوبی است که توضیح میدهد داده کجا ذخیره، کش یا مبادله میشود. باز هم جزئیات بیش از حد این حوزه را سنگین میکند و پیچیدگی غیرضروری میسازد. هدف این نوع نمودار قاب گرفتن حرکت داده و نشان دادن سطح بالای این است که داده کجا و چگونه جریان دارد، با توجه به اینکه داده چگونه وارد جهان شما میشود و چگونه دوباره از آن خارج میشود.
نمودارهای شبکه
نمودار شبکه خیلی با نمودار معماری متفاوت نیست، جز اینکه از لنز شبکهها و سرورهای واقعی تشکیلدهنده سازمان تولید میشود. نشانیهای شبکه مرتبط تشویق میشوند، از جمله هر مسیر، دیوار آتش یا دروازه که قطعهها را به هم وصل میکند. اگر سرورهای فیزیکی دارید، این نمودار باید نشان دهد ماشینهای فیزیکی کجا قرار دارند، مثلا مرکز داده و رک. سند دیگری مشخصات فیزیکی هر جزء را توضیح خواهد داد، از جمله تاریخ خرید و انقضا و سوابق پیکربندی.
۱۱.۲.۱۰ طرحوارههای داده
پایگاههای داده در قلب بیشتر سازمانهای شرکتها هستند و دادهها و رابطههای ارزشمندی را نگه میدارند که شرکت شما را زنده نگه میدهد. با این حال، با وجود اهمیت این نقش، یکی از کممستندترین حوزههاست؛ اما لازم نیست چنین باشد. طنز ماجرا این است که ابزارهای زیادی موجودند، مثل DB Schema، که میتوانند یک پایگاه داده رابطهای را دروننگری کنند و نمای کلی طرحواره را بکشند و کلید خارجیها را برای تولید رابطههای جدولها بشکافند. با گرفتن این بهعنوان پایه، میتوانید این نمودار را بهراحتی گسترش و حاشیهنویسی کنید تا دانش کسبوکار لازم برای معنا دادن به چیدمان داده اضافه شود.
پایگاههای داده مدرن همگی امکان افزودن کامنت مستقیم به جدولها و ستونها را پشتیبانی میکنند، بسیار شبیه اینکه کامنتها بخشی از فایلهای کد منبعاند. برخی ذخیرهگاه دادههای دیگر ممکن است کامنت درونخطی را پشتیبانی نکنند و بنابراین به مستندسازی بیرونی دستی نیاز داشته باشند. این چیزی است که باید به چرخه انتشار اضافه شود تا اگر چیزی تغییر کرد، یادداشتی برای بهروزرسانی مستندات وجود داشته باشد. تا زمانی که چیدمان و محل همه دادهها تا سطحی مستند باشد که افراد بعدی بتوانند دانش را پیدا و استفاده کنند، وضعیت خوبی دارید.
۱۱.۲.۱۱ مستندات انطباق
ممکن است خود را در صنعتی بیابید که باید سطحی از مستندات را نگه دارد؛ شامل گامهای فرایندی، گزارشهای ممیزی و گزارشهای خلاصه. صنایع سلامت و مالی نمونههای رایجیاند که نیاز بالاتری به مستندسازی دارند. برخی پروژههای دولتی و نظامی نیز سطحی از فرایند نشاندادهشده را طلب میکنند؛ استاندارد ISO یک نمونه است. جزئیات خاص HIPAA، PCI، ISO و مانند آن بیرون از دامنه این کتاب است. برای شرکتهایی که باید به گواهی مشخصی برسند، توصیه میشود با متخصص شخص ثالثی کار کنید که بتواند شما را از فرایند عبور دهد. برای مثال، شرکتهای بزرگ حسابداری دپارتمانهایی اختصاصی برای چنین ابتکارهایی دارند.
هرچند فرایند میتواند ترسناک به نظر برسد، اگر با ذهنیت درست با آن برخورد شود لازم نیست چنین باشد. هر استاندارد یا سطح انطباقی که هدف گرفتهاید، آن را مجموعهای از پروتکلهای عقل سلیم ببینید تا همه طرفها صادقانه کار کنند. سازمانهایی که هیچ مستند، فرایند و جریان ندارند بیشترین سختی را میکشند. همه چیز باید از صفر ساخته شود و مثل تلاشی بسیار طولانی حس میشود. آنهایی که مستندات و استانداردهای خوب دارند، درد را بهمراتب کمتر حس میکنند. بله، حوزههایی هست که باید رسیدگی شود و بخشهایی که باید سفتتر شود، اما همه در مسیر درست است. انطباق البته فقط مستندسازی نیست؛ باید حرف را عمل کنید. این ممکن است به تغییرات کد یا معماری نیاز داشته باشد، پس این موارد را فرصتهایی برای تنظیم دقیق و محکمسازی ببینید. بیشتر الزامات بزرگ انطباق بینشهای ارزشمندی درباره امنیت و مدیریت داده میدهند. اگر فکر میکنید سازمانتان در رادار انطباق قرار خواهد گرفت، شروع به مطالعه مقدماتی درباره کارهای لازم کنید، جلو بیفتید و این روشها را وارد DNA تیم خود کنید. آن را نشان افتخار بدانید. شما مسئول حفاظت از سیستمها و دادههای سازمانتان هستید. هر راهنمایی و کمکی را که میتوانید بگیرید.
۱۱.۲.۱۲ ردیابی مجوز و ممیزی
یک حوزه که رها کردنش آسان است، اما در نقطهای لازم خواهد شد، نیاز به جستوجو کردن مجوزها و داراییهای نرمافزاری است. در پایگاه دانش خود جایی بسازید تا سابقه همه وابستگیهای بیرونیتان به نرمافزار، چه خریداریشده و چه متنباز، نگه داشته شود. همه را تشویق کنید این را بهروز نگه دارند، کوچک یا بزرگ. هر بار که یک توسعهدهنده Java کتابخانه جدیدی به پروژه Maven خود اضافه میکند، یا یک توسعهدهنده JavaScript ماژول npm تازهای وارد میکند، بخشی از فرایند کنید که مستندات بهروز شود، شامل منبع و شرایط مجوز. فهرست نرمافزارها بخشی استاندارد از بررسی موشکافانه است و تا زمان نگارش، تیمی ندیدهام که این اطلاعات را آماده در اختیار داشته باشد. این فهرست برای گفتوگوهای دیگر نیز لازم است، مثل زمانهای تمدید و ارتقا، و برای کسانی که در ابر نیستند اما میخواهند بروند، فهم اینکه مجوزشان سازگار هست یا نه.
۱۱.۳ وایتپیپرها
اگرچه بهطور سختگیرانه بخشی از مستندات اصلی نیست، ارزش دارد وسیلهای را که به نام وایتپیپر شناخته میشود برجسته کنیم. وایتپیپر سندی منتشرشده است که برای خواندن توسط مخاطب بیرونی طراحی شده. فلسفه یا فرایندی مشخص را برای حوزهای خاص توضیح میدهد. وایتپیپرها زمانی بسیار مفیدند که سازمان شما باید پیش از آنکه پایگاه مشتریان واقعا بتواند از ارائه شما بهره ببرد، آنها را آموزش دهد. این سند که اغلب بخشی از چرخه فروش است، فرصتی عالی است تا حرفهایگری و عمق دانشی را نشان دهید که وارد چیزی شده است. وایتپیپر هیچ راز تجاری یا روش مهندسی جزئی را فاش نمیکند. طراحی شده تا طرف بیرونی را وارد خط فکری شما کند تا تعامل با محصولتان برای او آسانتر شود. نمونههایی از وایتپیپرها عبارتاند از:
- اصول امنیت API
- توصیههای استفاده از داده
- بهترین روشها برای یکپارچهسازیهای API
- تبدیلهای وضعیت داده
۱۱.۴ بهترین روشها
مستندسازی شاید جذابترین بخش نقش نباشد، اما یکی از بخشهای حیاتی است که مقیاس دادن و رشد دادن گروه مهندسی را روان میکند. در ادامه چند بهترین روش و نکته آمده تا شما را وارد ریتم کند:
- ابزار پایگاه دانش خود را با دقت انتخاب کنید تا تا حد ممکن ویژگیهای اصلی مستندسازی را در یک ابزار تحویل دهد.
- قالب بسازید تا تیم شما بتواند سریع به صفحهها اضافه کند. ویرایش کردن چیزی بسیار آسانتر از ساختن چیزی از صفر است.
- کوچک شروع کنید و آرام بسازید. این ماراتن است، نه اسپرینت.
- همه را تشویق کنید محتوا را با ایمیلها و پیامهای چت غنی کنند.
- ویدئو و اسکرینکست راههای سریعی برای کامل کردن محتوا هستند.
- توضیح اینکه کد منبع چه میکند را بخشی از فرایند بازبینی کد کنید.
- همه جزئیات فرایندی را هنگام مدیریت سیستمها تمرین کنید.
جمعبندی
- زود مستند کنید، وقتی دانش هنوز تازه است.
- انتخاب ابزار درست مشارکت همه را آسانتر میکند.
- ساده نگه دارید؛ این باعث میشود افرادی که کمتر متنمحورند احساس ترس نکنند.
- ویدئوها، یادداشتهای صوتی و نمودارها ابزارهای غنی برای ثبت جزئیاتاند.
- اعتبارسنجی هر چیزی که اجرای یک سیستم و مدیریت آن را توضیح میدهد مهم است.
- حتی یادداشتهای ساده یا نکتههای گلولهای بهتر از هیچ هستند.
چکلیست
چند مورد از موارد زیر را میتوانید ادعا کنید که پوشش دادهاید؟
- ابزار همکاریای فراهم کردهاید تا تیم شما دانش را در آن مشارکت دهد.
- سندی ساختهاید که توضیح میدهد سازمانتان چگونه ساخت و نگهداری شود.
- اجزا را، شامل جزئیات نسخه و مجوز، درون سازمانتان فهرست کردهاید.
- نموداری آسانفهم طراحی کردهاید که نشان میدهد فناوری شما چگونه چیده شده است.
- گامهای دقیق برای ساخت و بازیابی پشتیبانها را فهرست کردهاید.
- فرهنگ گشودگی و اشتراک دانش را تشویق کردهاید.
خلاصه هوش مصنوعی
خلاصه فصل
مستندسازی تداوم، مقیاسپذیری و آزادی سازمان است — نه کار اداری اختیاری. فصل انواع مستندات (معماری، عملیات، آنبوردینگ، تاریخچه تصمیم) و نقش نمودارها در ارتباط را برجسته میکند. مستندات بهروز از دو تله «تغییر بیفکر» و «ترس از دست زدن» جلوگیری میکند.
- مستندسازی باید برای مخاطب مناسب (تیم فنی، عملیات، مشتری) نوشته شود.
- نویسنده فنی با پیشینه مهندسی میتواند یادداشتها را به اسناد ساختاریافته تبدیل کند.
- مستندسازی را در فرایند روزانه بگنجانید؛ وگرنه به پروژه عظیم تبدیل میشود.
این خلاصه با کمک هوش مصنوعی بر اساس محتوای فصل تهیه شده و جایگزین مطالعه کامل متن نیست.