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

مطلبی که می‌خوانید ترجمه‌ قسمت ۳۱ از رادیو مهندسی نرم‌افزار است. رادیو مهندسی نرم‌افزار هر یکی دو هفته یک بار مصاحبه‌ای درباره‌ یکی از موضوعات حوزه‌ مهندسی نرم‌افزار با افراد خبره و با تجربه در موضوع مورد بحث ترتیب می‌دهد.

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

اندراس لطفاً کمی در مورد خودتان و موضوع مستند‌سازی چابک صحبت کنید.

سلام ، برای دعوتتان متشکرم. همین طور به شنوندگان سلام می‌کنم. من یک معمار و مهندس نرم‌افزار مستقل در هامبورگ هستم که بر روی پروژه‌های IT مختلفی کار کرده‌ام. خیلی وقت است که در این حوزه مشغولم. امروزه بیشتر تمرکزم بر روی معماری‌های مبتنی بر اینترنت و نرم‌افزارهای مدیریت محتوای تحت‌وب است. موضوع مستندسازی، موضوعی است که چند سالی است بر روی آن کار می‌کنم زیرا در هر پروژه‌ای، مستقل از نوع تکنولوژی‌‌اش، می‌توانیم سرمشق‌هایی (Best Practice) را در ارتباط با مستندسازی مشاهده کنیم که خوب عمل می‌کنند و چیزهایی را هم ببینیم که خوب عمل نمی‌کنند.

سرانجام، شروع کردم که این تجربه‌های مربوط به سرمشق‌ها را در قالب تعدادی الگو (Pattern) شکل بدهم و به این ترتیب بود که کتاب مستندسازی چابک نمو یافت. عنوان چابک از این موضوع ناشی می‌شود که خواسته‌ام بر روی چیزهایی که متدهای چابک‌ (Agile Method) در مورد مستندسازی می‌گویند، تأکید کنم. اینکه مستندسازی بیش از حد، بیش از آنکه خوب باشد، زیان‌بار است. و اینکه می‌توانیم از متدهای چابک‌، اطلاعات زیادی در ارتباط با اینکه مستندسازی خوب چیست و چه چیز نیست، بدست بیاوریم. فکر می‌کنم یکی از نکات مهمی که می‌توانیم از متدهای چابک‌ بیاموزیم این است که «مستندسازی» و «فراگیری»، یکسان نیستند. شما می‌توانید خیلی چیزها را مستند کرده باشید اما این به آن معنی نیست که همه چیزهایی که تیم فراگرفته است را مستند کرده‌اید. به همین ترتیب می‌توانید مستندات را بخوانید اما ممکن است همه دانشی که نویسندگان در ابتدای کار، در مستندات قرار داده‌اند را بدست نیاورید.

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

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

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

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

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

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

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

یک چیزی که دوست دارم اضافه کنم این است که به‌‌شکل خاص، اخیراً یک مشتری داشتم که من را استخدام کرد تا راهی بیابم که چگونه معماری‌شان را مستند کنیم. و این سئوال سختی بود زیرا آن‌ها کار را با نوشتن صدها صفحه مستند آغاز کرده بودند که کلی مفاهیم معماری، اینترفیس‌ها، بیان مشخصات و غیره را توضیح می‌داد اما متوجه شدند که هیچ‌کس آن را نمی‌خواند و اساساً بی‌فایده بوده است.
روش دیگری در مستندسازی معماری هم هست که لااقل در آن مورد، موفق‌تر بوده است و الان داریم انجام می‌دهیم. به این شکل است که تعدادی درس آموزشی (Tutorial) و راهنمای گام‌به‌گام (Walkthrough) بنویسیم زیرا مخاطبانی که این مستند، برای آن‌ها نوشته شده است، مدیران فنی سطح بالا نیستند که بخواهید برایشان، تصمیمات معماری‌تان را توجیه کنید. در عوض می‌خواهید برای توسعه‌دهندگان، چگونگی پیاده‌سازی سیستم بر اساس معماری را بیان کنید و این چیزی نیست که با نوعی مستند مرجع بخواهید بیان کنید بلکه به نوشته‌ای نیاز دارید که توسعه‌دهندگان در دست داشته باشند و با آن، بتوانند مسیر یک سناریوی مرسوم برنامه‌شان، را ببینند.
این، به همان مطلب مخاطبان هدف بر می‌گردد. باید نه تنها در مورد اینکه چه چیزهایی را می‌نویسید بلکه حتی در مورد روشی که آن را می‌نویسید نیز اطمینان یابید. به مسأله سبک‌های نگارش بر می‌گردد؛ اینکه آیا اول‌شخص، صحبت می‌کنید یا با افعال مجهول صحبت می‌کنید، که در نهایت به این بر می‌گردد که با چه کسی صحبت می‌کنید.

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

فکر می‌کنم سئوال مهم دیگری که باید در مورد آن بحث کنیم این است که چه زمان باید مستندسازی کنیم؟ آیا در انتهای پروژه وقتی همه چیز تمام شد؟ آیا همراه با کار، آن را انجام دهیم؟ بعنوان مثال JavaDoc از مثال‌های مرسومی است که همراه کار، آن را انجام می‌دهید و اصلاً جزء تعریف API است. آیا ایده‌ای دارید که چه زمانی موقع مناسب برای نوشتن هرکدام از انواع مستندات است؟

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

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

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

فکر می‌کنید این کار توسعه‌دهنده‌ها است که مستندسازی کنند یا فکر می‌کنید لازم است نویسندگان فنی داشته باشیم که مستندسازی کنند یا لااقل مستندات را بازبینی کنند؟

فکر می‌کنم در حالت کلی این توسعه‌دهنده‌ها و طراح‌ها هستند که باید کار خودشان را مستند کنند. خیلی دشوار است که افکار کس دیگری را مستند کنیم یا شاید غیرممکن باشد.

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

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

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

بله، می‌توانم تصورش کنم. اغلب قالب‌هایی برای مستندات دارید و در این کار می‌توانید فراتر از این بروید که فقط ساختار استاندارد را تعریف کنید. می‌توانید حتی فهرست مطالب استاندارد (Table of Content) را هم فراهم کنید تا به عنوان نوعی راهنما برای توسعه‌دهنده‌ها به خدمت گرفته شود تا متوجه شوند که برخی موارد که باید به آن اشاره می‌کردند را فراموش کرده‌اند. شما فقط کمک‌شان می‌کنید که مستندات ضروری را فراهم کنند.

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

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

باید تأیید کنم که من واقعاً دوست دارم چیزی را عالی مستند کنم که خودش عالی باشد. اگر طراحی و معماری عالی باشد، نوشتن مستند عالی برای آن هم گاهی لذت‌بخش است.
بیایید کمی در مورد ساختار یک مستند خوب صحبت کنیم. ما به شکل الگو (Pattern Form) اشاره کردیم اما این همه چیز نیست. آیا توصیه‌ای دارید که چگونه مستندات را به‌خوبی ساختار دهیم که برای مخاطبینِ بالقوه خوانایی خوبی داشته باشد؟

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

دیگر اینکه می‌توانید از تگ‌های ساخت‌یافته استفاده کنید. این می‌تواند خیلی مشابه با شکل الگو باشد اما می‌تواند هر نوع تگ‌های ساخت‌یافته‌ای و هر نوع اطلاعات تکرارشونده و سیستماتیک دیگر هم باشد. به‌عنوان مثال می‌توانید از جداول استفاده کنید. خیلی از افراد جامعه IT، تمایل دارند که به چیزها به شکل دسته‌ها و گروه‌ها نگاه کنند. بنابراین جداولی از ستون‌ها و سطرها برای جامعه IT، امری طبیعی هستند و چیزها را به شکل خیلی واضحی نمایش می‌دهند و خیلی آسان تولید می‌شوند. البته نمودارها هم می‌توانند خیلی مفید باشند. اِشکال‌ آنها این است که تولیدشان پرهزینه است. از طرف دیگر، می‌دانیم یک تصویر، گاهی [عملکردش] بیش از ۱۰۰۰ کلمه است. [تهیه تصاویر] در مورد طراحی و معماری، مقداری زمان می‌برد اما به کیفیت مستند می‌افزاید. اگر واقعاً می‌خواهید که ایده‌های طراحی و نمای کلی (Big Picture) یک معماری را برسانید، فکر می‌کنم می‌ارزد که نمودارهای واقعاً سودمند را مستند کنید.

فکر می‌کنم باید اشاره شود که نمودارها هیچ‌گاه به تنهایی جواب نمی‌دهند. وقتی ما کتاب الگوهای راه‌دور (Remoting Patterns) را نوشتیم، در آنجا طبعاً معماری زیرساخت‌های راه دور را توضیح دادیم. در آنجا، همواره در انتهای هر فصلی مجموعه‌ای از نمودار‌های توالی (Sequence Diagram) داشتیم که نشان می‌داد چطور مؤلفه‌های مختلفی که توضیح ‌داده‌ شده‌اند به هم دیگر می‌پیوندند و با هم تعامل می‌کنند. اما بازخوردی که از همه کسانی که کار را بازبینی کرده بودند، داشتیم این بود که: «نمودارهای توالی خوب هستند، اما لطفاً با متن ساده توضیح دهید که آنها شامل چه چیزی هستند.»
آن‌وقت من با خودم فکر می‌کردم: «عجب! یعنی شما نمی‌توانید نمودارهای توالی را بخوانید؟» اما نکته‌ای که من فهمیدم این بود که اغلب وقتی شما به یک نمودار نگاه می‌کنید در آن خیره می‌شوید و خیره می‌شوید و خیره می‌شوید تا اینکه یک چیزی را ببینید. اما به راهنمایی نیاز دارید تا شما را از میان نمودار عبور دهد و نقاط کانونی را نشان‌تان دهد و کمک‌تان کند که به کجا نگاه کنید و تمرکزتان را به چه جایی ببرید. بنابراین نمودارها به‌عنوان اطلاعات اضافی خوب هستند اما فکر می‌کنم نباید به‌عنوان منبع انحصاری اطلاعات استفاده شوند. بدترین شکلش این است که اگر مستندات شما در قالب یک مدل Rose بزرگ است، صرفاً بگویید: «فایل Rose را با نرم‌افزارش باز کرده و در آن بگردید.» من فکر نمی‌کنم این کار معمولاً مناسب باشد.

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

یک نظر دیگر در مورد آن -هرچند شاید نباید این‌قدر در مورد این موضوع صحبت کنیم- این است که اگر بخواهید یک سیستم یا معماری را به‌صورت سیستماتیک توضیح دهید، خیلی مهم است که شما به‌عنوان نویسنده بر روی تعداد محدودی از اصطلاحات و لغات توافق کنید. باید اطمینان یابید که از یک زبان سازگار استفاده می‌کنید و احتمالاً استفاده از یک واژه‌نامه (Glossary) می‌تواند به این منظور کمک کند. بنابراین در ابتدا، تعدادی اصطلاح را تعریف کنید. فرضاً اگر بخواهم شما را به مبحث برنامه‌نویسی به روش برآمده از مدل (Model Driven Development)، ارجاع دهم در حالت منتهایش، یک متامدل می‌کشید. به هرحال فکر می‌کنم حفظ سازگاری در اصطلاحاتی که استفاده می‌کنید و در روشی که برای بیان مطالب دارید، خیلی مهم است زیرا در غیر این صورت، تنها خواننده را گیج خواهید کرد.
اجازه دهید به برنامه مصاحبه‌مان برگردم. مطلبی هست که دوست دارم در مورد آن دقیق‌تر شویم: مستنداتی هستند که آنها را در قطار یا اتاق می‌خوانید و در مقابل مستنداتی هستند که در جستجو استفاده می‌شوند. مثلاً JavaDoc از اینگونه مستندات است. مواردی که تا کنون توضیح دادید در مورد کدام‌یک از این دو می‌توانند به‌کار روند؟ آیا از لحاظ اهمیت تفاوت دارند؟ آیا یکی از دیگری مهم‌تر است؟ ایده‌ای در این مورد دارید؟

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

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

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

این ما را به بحث تکنولوژی و تکنیک‌ها رهنمون می‌کند. آیا باید مستنداتم را در Word بنویسم یا از ابزارهای تولیدکننده مستندات و نمودارها از قبیل Rose و ... استفاده کنم؟ می‌دانم که این موضوع پیچیده‌ای است اما آیا در این مورد سرمشق‌هایی (Best Practice) هست که بخواهید توصیه کنید؟

فکر می‌کنم چیزی که شما می‌دانید این است که می‌توانید نماها (View) را بسازید اما نمی‌توانید محتوا را [به‌شکل خودکار] بسازید. در خیلی مواردی که می‌خواهید مستندی روی یک مدیا بسازید که آن را پرینت کنید، باید آن را بنویسید و نمی‌توانید آن را به‌صورت خودکار بسازید. اما آنچه می‌توانید تلاش کنید که به‌طور خودکار بسازید، مربوط به همپوشانی‌ها است. مثلاً اگر می‌خواهید یک مستند به‌صورت HTML و هم در وب در دسترس باشد، در آن صورت این گزینه وجود دارد که یک نمای آن، احتمالاً نمای وب آن را به‌صورت خودکار بسازید. یکی از مثال‌های برجسته تولید خودکار مستندات، JavaDoc است. همه می‌دانند و همانطور که می‌بینید خیلی سودمند است که مستقیماً از کد و [مستندات] کنار کد به مستندات و بیان مشخصات API برسیم. بنابراین می‌توانید از تکنیک‌هایی استفاده کنید که از یک اطلاعات واحد، نماهای مختلفی تولید کنید اما به‌صورت عمومی تولید خودکار مستندات، محدودیت دارد.

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

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

یک قاعده این است که نباید از فونت‌های مختلف استفاده کنیم. گاهی مواقع در یک مستند، ۴، ۵ یا ۶ نوع فونت استفاده می‌شود. این خواندنش را خیلی سخت می‌کند. خوب است که از فونت نوع Serif به عنوان فونت اصلی (نه لزوماً برای تیترها) استفاده کنید (به فونت‌هایی که لبه‌های زبانه‌دار دارند، فونت‌های Serif گفته می‌شود - مترجم). زیرا این نوع فونت خوانایی بیشتری دارد و شواهدی هم برای آن هست؛ هم‌اکنون ما بیش از ۵۰ سال تجربه داریم که چه نوع تایپوگرافی، به خوانندگان کمک می‌کند تا بهتر بخوانند. یک مثال افراطی این است که فقط از حروف بزرگ استفاده کنیم. برخی افراد این کار را می‌کنند تا بخش‌هایی از متن که خیلی مهم انگاشته می‌شوند را مشخص کنند. اما اگر در تمام متن آن را استفاده کنید، متن کاملاً ناخوانا می‌شود و خواندن متن تا ۲۰٪ الی ۳۰٪ بیشتر طول خواهد کشید و نتیجه‌اش این می‌شود که اصلاً آن را نمی‌خوانند.

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

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

اگر خطی داشته باشید که خیلی کوتاه باشد، ممکن است مناسب باشد و این همان چیزی است که در روزنامه‌ها داریم اما در این‌ صورت مجبور می‌شوید بیشتر از خطی به خط دیگر بروید. باید یک اندازه منطقی برای طول خط در کاغذهای مربوط به محیط‌های عادی داشته باشید. یعنی چیزهایی که در خانه بر روی میز خوانده می‌شوند. اگر طول خط‌ها خیلی زیاد باشد، ناخوانا می‌شود زیرا افراد خطوط را قاطی می‌کنند. این‌ها چیزهایی است که ناآگاهانه اتفاق می‌افتد و می‌توانید تأثیرات آن را اندازه بگیرید. قاعده کلی این است که در حدود دو سری الفبای کوچک در یک خط جا شود. همین طور، در مورد فاصله خطوط، هم قاعده کلی این است که فاصله خطوط ۱.۲ برابر اندازه فونت باشد یعنی اگر اندازه فونت شما ۱۰ پیکسلی است نیاز به ۱۲ پیکسل برای هر خط دارید. این همان چیزی است که اغلب ویرایشگرها به درستی انجام می‌دهند اما ارزش دارد که آن را چک کنید.

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

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

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

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

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

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

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

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

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

ضبط کردن، به نظر ایده خوبی می‌آید. ضبط ویدئویی یا mp3 به نظر سودمندتر از یک تصویر ساده می‌آید.

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

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

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

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

اگر بگویم حتی می‌توانید رویه‌های (Practice) چابک بیشتری را استفاده کنید بیراه گفته‌‌ام؟ مثلاً [اگر این رویه را دارید] که مشتری را در سایت خود دارید، [در مستندسازی] این معنی را می‌دهد که می‌توانید مشتری را برای نوشتن مستندات استفاده کنید یا می‌توانید در نوشتن مستندات جفت شوید. یا اگر توسعه برآمده از تست (Test Driven Development) دارید، [در مستندات] هم معنی می‌دهد که ابتدا تعریف کنید که اهداف‌ مستندسازی چیست و تعریف ‌کنید که مخاطبان مستند، چه کسانی هستند؛ اینکه اول تعریف کنید می‌خواهید به چه چیزی برسید و بعد، شروع به مستندسازی کنید. در واقع، تکنیک‌‌های موجود در متدهای چابک بیشتری وجود دارد که می‌تواند به طریقه دیگری برای مستند‌سازی هم بیان شود.

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

فکر می‌کنم بحث‌مان به پایان می‌رسد. از شرکت در مصاحبه ممنونم.

از اینکه من را دعوت کردید، ممنونم.