داکیومنت نویسی پروژه نرم افزاری

مستندسازی برای یک پروژه نرم افزاری | راه های مستند سازی برای یک پروژه نرم افزار

من به عنوان یک مهندس نرم افزار از تیم نرم افزاری i-dev وقت زیادی را صرف خواندن و نوشتن اسناد طراحی می کنم. بعد از گذشتن از صدها مورد از این اسناد ، من دست اول را دیدم که رابطه مستندی بین اسناد طراحی خوب و موفقیت نهایی پروژه وجود دارد.

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

مقاله به ۴ بخش تقسیم شده است:

• چرا یک سند طراحی بنویسید
• چه چیزی را در یک سند طراحی گنجانید
• چگونه آن را بنویسیم
• روند پیرامون آن

چرا یک سند طراحی می نویسید؟

یک سند طراحی – همچنین به عنوان یک مشخصات فنی شناخته می شود – توضیحی درباره چگونگی برنامه ریزی برای حل مسئله است.

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

یک سند طراحی مفیدترین ابزار برای اطمینان از انجام کار صحیح است.

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

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

عالی! اگر هنوز در حال خواندن هستید ، به اهمیت اسناد طراحی اعتقاد دارید. با این حال ، تیمهای مختلف مهندسی و حتی مهندسین در همان تیم ، غالباً اسناد طراحی را بسیار متفاوت می نویسند. بنابراین اجازه دهید در مورد محتوا ، سبک و روند یک طراحی خوب طراحی کنیم.

چه چیزی را می توان در یک سند طراحی گنجانید؟

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

برای شروع ، موارد زیر لیستی از بخش هایی است که حداقل باید در مستندات طرح بعدی خود در نظر بگیرید:

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

خلاصه سطح بالایی که هر مهندس شرکت باید درک کند و از آن استفاده کند تا تصمیم بگیرد خواندن بقیه مقاله برای آنها مفید است یا خیر. باید حداکثر ۳ پاراگراف باشد.

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

بخش اهداف باید:

تأثیر کاربر محور پروژه خود را توصیف کنید – جایی که کاربر شما ممکن است تیم مهندسی دیگری یا حتی یک سیستم فنی دیگر باشد

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

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

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

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

تاریخ شروع: ۷ ژوئن ۲۰۱۸

Milestone 1 – سیستم جدید MVP که در حالت تاریک اجرا می شود: ۲۸ ژوئن ۲۰۱۸

Milestone 2 – سیستم قدیمی بازنشسته: ۴ ژوئیه ۲۰۱۸

تاریخ پایان: ویژگی X، Y، Z را به سیستم جدید اضافه کنید: ۱۴ ژوئیه ۲۰۱۸

اگر ETA برخی از این نقاط عطف تغییر کند ، زیر مجموعه [بروزرسانی] را در اینجا اضافه کنید ، بنابراین سهامداران می توانند به روزترین تخمین ها را مشاهده کنند.

راه حل موجود

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

یک داستان کاربر یک روش عالی برای قاب کردن این موضوع است. به خاطر داشته باشید که سیستم شما ممکن است دارای انواع مختلفی از کاربران با موارد استفاده متفاوت باشد.

راه حل پیشنهادی

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

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

راه حل های جایگزین

در هنگام ارائه راه حل بالا چه چیز دیگری را در نظر گرفتید؟ جوانب مثبت و منفی گزینه ها چیست؟ آیا فکر کرده اید که راه حل شخص ثالث – یا استفاده از منبع آزاد – این مشکل را بر خلاف ساختن خودتان حل می کند؟

قابلیت تست ، نظارت و هشدار

من این بخش را دوست دارم ، زیرا مردم غالباً این کار را بعنوان یک رفتار پسندیده و یا همه آن را کنار می گذارند ، و تقریباً همیشه برمی گردیم تا وقتی اوضاع شکسته می شود ، بعداً آنها را گاز بگیریم و آنها نمی دانند چگونه یا چرا.

تأثیر متقابل تیم

این امر در صورت تماس و توسعه بار چگونه افزایش می یابد؟

هزینه آن چقدر است؟

آیا این امر باعث ایجاد رگرسیون تاخیری در سیستم می شود؟

آیا این آسیب پذیری های امنیتی را در معرض خطر قرار می دهد؟

عواقب منفی و عوارض جانبی چیست؟

چگونه تیم پشتیبانی می تواند این موضوع را با مشتریان ارتباط برقرار کند؟

سوالات باز

هرگونه مسئله علنی که به آنها اطمینان ندارید ، تصمیمات ضد و نقیضی است که دوست دارید خوانندگان به این موضوع بپردازند ، کارهای آینده را پیشنهاد دهند و موارد دیگر. یک نام از زبان در این بخش “ناشناخته های شناخته شده” است.

SCOPING دقیق و جدول زمانی

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

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

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

چگونه آن را بنویسیم

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

تا حد امکان بنویسید

سعی نکنید مانند مقالات دانشگاهی که خوانده اید بنویسید. آنها برای تأثیرگذاری بر داوران مجله نوشته شده است. سند شما برای توصیف راه حل و گرفتن بازخورد از هم تیمی های شما نوشته شده است. شما می توانید با استفاده از:

– کلمات ساده

– جملات کوتاه

– لیست های بولت و / یا لیست های شماره گذاری شده

– نمونه های مشخص ، مانند “کاربر آلیس حساب بانکی خود را وصل می کند ، سپس …”

نمودارها و نمودارهای زیادی اضافه کنید

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

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

شماره ها را درج کنید

مقیاس مسئله اغلب راه حل را تعیین می کند. برای کمک به داوران به درک وضعیت جهان ، شماره های واقعی مانند # ردیف های DB ، # خطاهای کاربر ، تأخیر – و نحوه استفاده این مقیاس ها را درج کنید. یادآوری Big-O خود را به خاطر دارید؟

سعی کنید بامزه باشید

مشخصات یک مقاله دانشگاهی نیست. همچنین ، مردم خواندن چیزهای خنده دار را دوست دارند ، بنابراین این یک روش خوب برای نگه داشتن خواننده است. از این مسئله غافل نشوید ، اگرچه از ایده اصلی دور شوید.

اگر شما نیز مانند من ، بامزه باشید ، جوئل اسپولسکی (بدیهی است که با استعدادهای کمدی شناخته شده است …) این نکته را دارد:

یکی از ساده ترین راه ها برای خنده دار بودن ، خاص بودن در هنگام فراخواندن [… مثال:] به جای گفتن “منافع ویژه” ، بگویید “کشاورزان چپ آووکادو”.

تست شکاک را انجام دهید

قبل از ارسال سند طراحی خود به دیگران برای بررسی ، تصویب کنید که داوری کننده این طرح است. چه سوالات و شبهاتی ممکن است در مورد این طرح داشته باشید؟ سپس پیش از این به آنها بپردازید.

آزمون تعطیلات را انجام دهید

اگر اکنون به تعطیلات طولانی و بدون دسترسی به اینترنت می روید ، آیا شخصی در تیم شما می تواند این سند را بخواند و آن را طبق برنامه ای که شما در نظر گرفته اید ، پیاده کند؟

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

پردازش

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

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

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

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

۱- از یک مهندس باتجربه یا رهبر فنی در تیم خود بخواهید که داور شما باشد. در حالت ایده آل این کسی خواهد بود که به خوبی با احترام و یا آشنایی کامل با موارد حاشیه این مشکل را نشان دهد در صورت لزوم آنها را با boba رشوه دهید.

۲- با یک تخته سفید به یک اتاق کنفرانس بروید.

۳- مشکلی که برای این مهندس برطرف می کنید را توصیف کنید (این یک مرحله بسیار مهم است ، آن را نادیده بگیرید!).

۴- سپس عملیاتی را که در ذهن دارید توضیح دهید و آنها را متقاعد کنید که این کار درستی است.

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

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

در این یادداشت ، برای بررسی جنبه های خاص طراحی ، نظر سنجی ویژه (مانند SRE و مهندسین امنیتی) را در نظر بگیرید.

هنگامی که شما و داوران (بازدید کنندگان) از سیستم خارج شوید ، احساس کنید که می توانید سند طراحی را برای بازخورد و اشتراک دانش بیشتر به تیم خود ارسال کنید. من برای جلوگیری از تأخیرهای طولانی پیشنهاد می کنم این روند جمع آوری بازخورد را حدود ۱ هفته محدود کنید. تعهد خود را برای پرداختن به کلیه سوالات و نظرات افراد در طی آن هفته ترک کنید. گذاشتن نظرات حلق آویز = کارما بد.

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

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

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

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

سرانجام ، بگذارید یک ثانیه واقعاً متا به دست بیاوریم: چگونه موفقیت یک سند طراحی را ارزیابی می کنیم؟

همکار من کنت راکیپ پاسخ خوبی در این باره دارد:

اگر ROI صحیح کار انجام شود ، یک سند طراحی موفقیت آمیز است. این بدان معناست که یک طراحی موفقیت آمیز در واقع می تواند به نتیجه ای مانند این منجر شود:

۱- شما ۵ روز را صرف نوشتن مستندات طراحی خود می کنید ، این باعث می شود که در بخش های مختلف معماری فنی فکر کنید

۲- از بازرسان بازخورد دریافت می کنید که X خطرناکترین بخش معماری پیشنهادی است

۳- شما تصمیم می گیرید که برای اولین بار X را برای ریسک زدایی پروژه اجرا کنید

۴- ۳ روز بعد ، شما می فهمید که X یا امکان پذیر نیست ، یا بسیار سخت تر از آن است که در ابتدا در نظر گرفته شده باشید

۵- شما تصمیم می گیرید که کار خود را روی این پروژه متوقف کنید و در عوض کارهای دیگر را اولویت بندی کنید

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

منبع: virgool.io