چگونه یک سند طراحی نرم‌افزار مؤثر بنویسیم

یک سند طراحی باید مشکلات دشواری را که حل می‌کنید به‌وضوح بیان کند و به هم‌تیمی‌هایتان کمک کند تا بازخورد مفیدی به شما بدهند. این را بدانید که همیشه اصول ثابت است این جزئیات است که تغییر می‌کند

چه زمانی باید سند طراحی بنویسید؟

هرچه پروژه پیچیده‌تر یا پرریسک‌تر باشد، نوشتن سند طراحی ارزشمندتر است.

این سوالات را در نظر بگیرید:

• آیا چندین نفر برای پیاده‌سازی طراحی هماهنگ می‌شوند؟

• آیا پروژه بیش از سه ماه کار تمام‌وقت توسعه نیاز دارد؟

• آیا پیاده‌سازی برای چندین سال در محیط تولید (Production) اجرا خواهد شد؟

• آیا پروژه شامل همکاری بین چند تیم است؟

• آیا اهداف و الزامات پروژه مبهم هستند؟

• آیا خطرات فاجعه‌باری وجود دارد که بتوانید در مرحلهٔ طراحی از آنها پیشگیری کنید (مثلاً نقص‌های امنیتی، خطرات قانونی)؟

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

چقدر باید روی سند طراحی خود سرمایه‌گذاری کنید؟

یک سند طراحی می‌تواند یک صفحهٔ ساده باشد یا یک سند ۵۰ صفحه‌ای که نیاز به تأیید پنج تیم مختلف دارد. شما باید تصمیم بگیرید که چه میزان جزئیات منطقی است.

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

چه چیزی در سند طراحی جای می‌گیرد؟

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

به‌عنوان یک قانون سرانگشتی، می‌توانید یک سوال ساده بپرسید تا تصمیم بگیرید که آیا یک تصمیم در سند طراحی شما جای می‌گیرد یا نه: هزینهٔ اشتباه کردن چقدر است؟

هزینه اشتباه کردن چقدر است؟

همهٔ تصمیمات طراحی به یک اندازه مهم نیستند. برخی انتخاب‌ها به‌طور قابل‌توجهی انعطاف‌پذیرتر از بقیه هستند.

برای مثال، اگر یک برنامهٔ وب را به زبان C++ بسازید و بعد از نوشتن ۲۰۰ هزار خط کد متوجه شوید که Ruby on Rails انتخاب بهتری بوده، گیر کرده‌اید. بازنویسی از صفر هرگز جواب نمی‌دهد و حتی اگر موفق به نوشتن کد جدید در Rails شوید، همچنان بار نگهداری کد در دو زبان کاملاً متفاوت بر دوش شما خواهد بود.

برخی دیگر از تصمیمات طراحی پیش‌پاافتاده هستند. برای مثال، اگر برنامهٔ شما لیستی از ۱۰۰۰ مقاله را نمایش می‌دهد، آیا باید همهٔ آنها یکجا ظاهر شوند؟ یا کاربر باید ۲۰ تا را ببیند و روی دکمهٔ «بارگیری بیشتر» کلیک کند تا ۲۰ تای بعدی را ببیند؟

این موضوع اهمیتی ندارد.

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

اجزای یک سند طراحی

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

عنوان

اولین چیزی که پروژهٔ شما نیاز دارد یک عنوان است. این راهی است که افراد در مکالمات به پروژهٔ شما اشاره می‌کنند، بنابراین هدف خود را روی ویژگی‌های زیر قرار دهید:

• کوتاه: به‌راحتی تلفظ شود.

• متمایز: مشخص کند که به کدام پروژه اشاره دارد.

• گویا: از نظر مفهومی، پروژهٔ شما را نشان دهد.

برای مثال، اگر قصد دارید یک لایهٔ کش (Caching) بین سرور برنامه و سرور پایگاه دادهٔ خود اضافه کنید، RecencyBank نام خوبی است. تلفظ آن آسان است و هدف پروژه را توصیف می‌کند. یک نام بد، «پروژهٔ اسب‌ نقره ای پرنده» است زیرا طولانی و بی‌معناست.

فراداده (Metadata)

کسل‌کننده اما مفید، فراداده به خواننده کمک می‌کند تا زمینهٔ اولیهٔ سند شما را درک کند:

• نویسنده کیست؟ (نام + آدرس ایمیل)

• سند را چه زمانی ایجاد کردید؟

• URL معتبر چیست؟

  • مخصوصاً اگر سازمان شما از تغییرمسیرهای لینک کوتاه مانند http://go/recency-bank استفاده می‌کند.

Metadata

Author: mhdi rezaei (mhdi@example.com)
Status: Ready for review
Created: 2026-06-22
URL: http://go/recency-bank-design

هدف (Objective)

هدف، توضیحی یک‌جمله‌ای از هدف پروژهٔ شماست. باید در صفحهٔ اول سند شما و به زبانی ساده که تمام ذی‌نفعان متوجه شوند، ظاهر شود.

Objective

Improve application performance by adding a caching layer between the Trogdor web server and the Postgres database.

پیش‌زمینه (Background)

بخش پیش‌زمینه، زمینه و انگیزهٔ پروژه را توضیح می‌دهد. باید به این سوالات پاسخ دهد:

• چرا تیم این پروژه را انجام می‌دهد؟

• این پروژه چه مشکلی را حل می‌کند؟

• آیا تلاش‌های قبلی برای حل این مشکل وجود داشته است؟

Background

When we launched the Trogdor web app in 2023, pages typically loaded in 100ms or less. After three years, median page loads have ballooned to 600ms, which causes users to perceive our app as sluggish.

We investigated the slowdown and discovered that database lookups make up 80% of page load times. As our data store has grown larger, database lookups have gotten slower.

We also discovered that 95% of database lookups are for the same 3% of database rows. This pattern of usage benefits greatly from memory-backed caching. The cache would serve frequently-accessed data faster and reduce database load for all other queries.

مدارک مرتبط

اگر این پروژه به مدارک دیگری متصل است، به آنها لینک دهید تا خواننده به‌راحتی آنها را پیدا کند.

اهداف (Goals)

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

از تعیین اهداف بر اساس جزئیات پیاده‌سازی خودداری کنید. اهداف شما باید نشان دهند که پروژه چگونه به کاربران، تیم یا شرکت شما سود می‌رساند.

غیر-اهداف (Non-goals)

در حالی که اهداف مشخص می‌کنند چه چیزی در محدودهٔ پروژه قرار دارد، بخش غیر-اهداف مشخص می‌کند چه چیزی خارج از محدوده است.

آیا اهدافی وجود دارند که خوانندگان ممکن است به‌اشتباه فرض کنند در محدودهٔ پروژه شما هستند؟ اگر چنین است، آنها را به‌عنوان غیر-هدف صریح اضافه کنید.

سناریوها (Scenarios)

اگر هدف شما چیزی مانند «افزودن دکمهٔ «اشتراک‌گذاری به‌عنوان URL» به نمودارها» باشد، ممکن است خواننده متوجه نشود که این در عمل چگونه به نظر می‌رسد.

بخش سناریوها به شما امکان می‌دهد برای خواننده خود تصویر کنید که سیستم تکمیل‌شدهٔ شما در دنیای واقعی چگونه کار می‌کند.

نمودارها (Diagrams)

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

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

اگر مطمئن نیستید چه چیزی باید در یک نمودار باشد، به این سوالات فکر کنید:

• داده‌ها چگونه در سیستم شما جریان می‌یابند؟

• اجزای مختلف سیستم شما چگونه در کنار هم قرار می‌گیرند؟

• سیستم شما چگونه با وابستگی‌ها و مشتریان پایین‌دستی خود تعامل دارد؟

• پروتکل‌های ارتباطی که سیستم شما تعریف می‌کند، کدامند؟

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

Excalidraw ،draw.io و Google Drawings ابزارهای نمودارکشی محبوبی هستند که بازبینی را تسهیل می‌کنند. همچنین زبان‌هایی مانند Mermaid، D2 و Graphviz وجود دارند که به شما امکان می‌دهند نمودارها را به‌صورت برنامه‌نویسی تولید کنید به یاد داشته باشید که به فایل نمودار یا کد لینک دهید تا هم‌تیمی‌هایتان نیز راهی برای بازتولید نمودار داشته باشند.

واژه‌نامه (Glossary)

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

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

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

اهداف سطح خدمات (SLOs)

SLOها اهداف قابل اندازه‌گیری هستند که یک سرویس به مشتریان یا کاربران خود ارائه می‌دهد. احتمالاً با توافق‌نامه‌های سطح خدمات (SLAs) آشنا هستید. SLAs در واقع SLOها به علاوهٔ جریمه‌های مالی برای کوتاهی هستند.

در داخل یک شرکت، معمولاً همکاران خود را به‌خاطر اشتباهات جریمه مالی نمی‌کنید. بنابراین، اسناد طراحی SLOها را تعریف می‌کنند نه SLAها.

یک SLO یک معیار عینی و قابل اندازه‌گیری برای عملکرد سیستم شما ایجاد می‌کند. مدیر شما ممکن است به شما بگوید که برنامهٔ شما باید «روی موبایل کارآمد باشد»، اما این مبهم است. شما نمی‌خواهید تا زمان تکمیل کد صبر کنید تا متوجه شوید که تعریف مدیر شما از «کارآمد» تأخیر کمتر از ۲ میلی‌ثانیه است. یک SLO به‌خوبی تعریف‌شده با بیان اهداف به صورت عینی و ملموس از ابهام جلوگیری می‌کند.

جدول زمانی (Timeline)

بخش جدول زمانی، پروژهٔ شما را به نقاط عطف (Milestone) تقسیم می‌کند و مشخص می‌کند که ذی‌نفعان پروژه چه زمانی تحویل‌دادنی‌های خود را دریافت می‌کنند.

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

اگر نمی‌دانید چگونه جدول زمانی پروژه را تخمین بزنید، به‌شدت مقالهٔ جوئل اسپولسکی، «برنامه‌های زمانی نرم‌افزاری بدون دردسر» را توصیه می‌کنم. این مقاله ۲۵ سال قدمت دارد، اما همچنان استراتژی تخمین نرم‌افزاری مورد علاقهٔ من است.

وابستگی‌ها / زیرساخت (Dependencies / Infrastructure)

بخش وابستگی‌ها باید به سوالاتی مانند این پاسخ دهد:

• از چه زبان(های) برنامه‌نویسی استفاده خواهید کرد؟

• کد روی چه سخت‌افزار یا سرویسی اجرا می‌شود؟

• داده‌های پایدار (Persistent Data) کجا ذخیره خواهند شد؟

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

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

ملاحظات قانونی (Legal Considerations)

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

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

جمع بندی

درنهایت همواره باید بدانید تهیه یک سند طراحی بسیار وابسته با شرایطی است که شما در آن مشغول به کار هستید هر کدام از این متغییرهای محیطی میتواند به طور کلی بر تمام فرآیند طراحی سند تاثیر مستقیم داشته باشد توجه کنید هیچ کدام از اینها شرایط اصلی که در بالا آورده شده را تغییر نمیدهد بله تنها در جزئیات تفاوت ایجاد میکند.