کتاب Docs for Developers با نام کامل An Engineer’s Field Guide to Technical Writing یک منبع بسیار جالب و عالی برای برنامه‌نویسان و مدیران پروزه است که می‌خواهند برای پروژه و یا کار برنامه‌نویسی خود مستندات داشته باشند. این کتاب در 11 فصل به شرح مفصل این کار بسیار مهم پرداخته و به همراه مثال‌هایی در دنیای واقعی این کار را برای شما راحت و آسان می‌کند.
در ادامه مقدمه‌ای از کتاب Docs for Developers را شرح خواهیم داد.
مقدمه‌ای بر کتاب Docs for Developers:
ساعت چهار صبح است و پیجر شما خاموش می‌شود. سرویس شرکت شما از کار افتاده است و مشتریان در هراس هستند. شما در یک پایگاه کد نیمه آشنا به تقلا می‌افتید و علت اصلی را جستجو می‌کنید. پیام های خطا در آزمون های واحد به طرز ناامیدکننده‌ای نامشخص هستند و README داخلی شامل سرفصل‌هایی است که به دنبال آن پاراگراف‌های یک کلمه‌ای تکرار می‌شوند: [TODO]. چه کسی این را نوشته است، تعجب می‌کنید.
با احساس غرق شدن، متوجه می شوید که به کد چهارده ماه پیش خود نگاه می‌کنید و تقریباً همه چیز را در مورد آن فراموش کرده‌اید. شما حافظه خود را برای یادآوری کاری که انجام می‌دادید، چرایی انجام این کار به این روش، و اینکه آیا برای مجموعه خاصی از موارد لبه بررسی یا آزمایش کرده‌اید، جستجو می‌کنید.
در همین حال، مشتریان شما بلیط پشتیبانی را بعد از بلیط پشتیبانی باز می‌کنند و پاسخ می‌خواهند. کلمات خود شما دوباره به ذهن شما خطور می‌کند: کد خود مستندسازی است.
یا شاید خدمات شما عالی عمل می‌کند و بهتر می‌شود. با ثبت نام بیشتر مشتریان، سؤالاتی دارند. تعداد زیادی از سؤال‌ها، ایمیل‌ها و تیکت‌های پشتیبانی با افزایش مقیاس خدمات شما سرازیر می‌شوند و به طور فزاینده‌ای از توسعه و پشتیبانی خارج می‌شوید.
به عنوان دانشمندترین فرد در مورد آنچه ساخته‌اید، محکوم به تقویمی پر از جلسات پشتیبانی فردی هستید که به یک سوال شش نفر مختلف پاسخ می دهد. می‌دانید که اگر فرصتی برای تحقیق و نوشتن نحوه کار وجود داشته باشد می توانید مشکل را برطرف کنید، اما آنقدر مشغول پاسخ دادن به سؤالات کاربران هستید که هرگز وقت ندارید.
حال سناریوی دیگری را تصور کنید: کد شما کامنت شده و README های شما دقیق و به روز هستند. شما یک راهنمای شروع و مجموعه‌ای از آموزش‌ها دارید که موارد استفاده برتر کاربران را هدف قرار می‌دهد. وقتی کاربر از شما کمک می‌خواهد، به او اسنادی را نشان می‌دهید که واقعاً مفید هستند. آن هشدار پیجر چهار صبح؟ حل آن پنج دقیقه طول کشید زیرا با اولین جستجوی خود آنچه را که نیاز داشتید پیدا کردید. مستندات مؤثر توسعه‌دهنده، آخرین سناریو را ممکن می‌سازد.
ممکن است این جمله را شنیده باشید که اغلب به اشتباه نقل می‌شود که می‌گوید کد خوب خود مستند است. درست است که نام‌گذاری، انواع، طراحی و الگوهای خوب درک کد را آسان‌تر می‌کند.
اما پروژه‌هایی با پیچیدگی و مقیاس کافی (یعنی اکثر پروژه‌هایی که ارزش ساخت دارند) به اسناد قابل خواندن توسط انسان نیاز دارند تا به دیگران کمک کند به سرعت بفهمند شما چه چیزی می‌سازید و چگونه از آن استفاده کنید. نویسندگان کتاب Docs for Developers به تعدادی از سازمان‌ها کمک کرده‌اند تا اسناد توسعه‌دهنده بزرگی را ایجاد کنند، از جمله شرکت‌های فناوری بزرگ، استارت‌آپ‌های سریع، سازمان‌های دولتی و کنسرسیوم‌های منبع باز. هر یک از ما سال‌ها تجربه ایجاد اسناد توسعه‌دهنده، گوش دادن و کار با توسعه‌دهندگان، و به طور کلی غوطه‌ور شدن در هر جنبه از اسناد توسعه‌دهنده در هر مقیاسی داریم.
ما به توسعه‌دهندگان بی‌شماری از سناریوهای کابوس توصیف شده در بالا کمک کرده ایم. هرچه بیشتر کمک می‌کردیم، بیشتر متوجه می‌شدیم که یک آغازگر برای توسعه‌دهندگانی که به دنبال ایجاد مستندات هستند وجود ندارد. بنابراین، ما به سر کار رفتیم و راه حلی را برای مشکلی که توسعه‌دهندگان مشاهده کردیم، ثبت کردیم.
ما این راهنمای میدانی برای مستندات فنی را با تکیه بر تخصص خود و بازخوردهای بسیاری از توسعه‌دهندگان ایجاد کردیم. این به عنوان منبعی برای نگهداری طراحی شده است، بنابراین می‌توانید اسناد را به عنوان بخشی از فرآیند توسعه نرم افزار خود بنویسید.
کتاب Docs for Developers شما را در ایجاد مستندات از ابتدا راهنمایی می‌کند. با شناسایی نیازهای کاربران شما و ایجاد طرحی با الگوهای رایج مستندسازی شروع می‌شود، سپس در فرآیند پیش‌نویس، ویرایش و انتشار محتوای شما حرکت می‌کند.
کتاب Docs for Developers با توصیه‌های عملی در مورد یکپارچه سازی بازخورد، اندازه‌گیری اثربخشی و حفظ اسناد و مدارک شما در طول رشد، به پایان می‌رسد. هر فصل به طور متوالی بر اساس فصل‌های قبلی است، و توصیه می‌کنیم حداقل در اولین مطالعه کتاب را به ترتیب دنبال کنید.
در سراسر کتاب Docs for Developers، داستان‌هایی درباره یک تیم توسعه‌دهنده که بر روی یک سرویس تخیلی به نام Corg.ly کار می‌کنند، گفته خواهد شد. Corg.ly سرویسی است که واق واق را به زبان انسان ترجمه می‌کند. Corg.ly از یک API برای ارسال و دریافت ترجمه استفاده می‌کند و از یک مدل یادگیری ماشین برای بهبود منظم ترجمه‌های خود استفاده می‌کند.
تیم Corg.ly متشکل از:
• شارلوت: مهندس اصلی در Corg.ly، وظیفه دارد راه‌اندازی Corg.ly به صورت عمومی در یک ماه با توسعه‌دهنده مستندات.
• Karthik: یک مهندس نرم‌افزار در Corg.ly که با آن کار می‌کند شارلوت.
• Mei: یکی از اولین مشتریان برای ترجمه Corg.ly سرویس.
• Ein: طلسم دفتر و آزمایش‌کننده بتا برای Corg.ly. یک کورگی
در نهایت، کتاب Docs for Developers به طور عمدی در مورد ابزارها و چارچوب‌ها انسان‌شناسی است. ممکن است ناامید کننده به نظر برسد که ما به شما نمی‌گوییم به زبان نشانه‌گذاری خاصی بنویسید یا با یک مولد سایت ایستای خاص که به طور خودکار با یک ابزار یکپارچه‌سازی مداوم به روز می‌شود، منتشر کنید.
در این کتاب شفافیت زیادی وجود ندارد: زبان‌ها و ابزارهایی که به بهترین شکل کار می‌کنند، نزدیک‌ترین زبان‌ها به کد و ابزار شما هستند. اگر تا پایان کتاب Docs for Developers همچنان به دنبال راهنمایی بیشتر در مورد ابزارسازی هستید، ضمیمه‌ای از منابع ارائه می‌دهیم که می‌توانید از آن‌ها برای یافتن اطلاعات اضافی و ابزارهای مستندسازی مناسب برای نیازهای خود استفاده کنید.
همچنین شما می‌توانید برای مطالعه در مورد الگوریتم‌های مهم دنیای رایانه از کتاب 40 Algorithms Every Programmer Should Know نیز استفاده نمائید.
سرفصل‌های کتاب Docs for Developers:
- About the Authors
- Acknowledgments
- Foreword
- Introduction
- Chapter 1: Understanding your audience
- Chapter 2: Planning your documentation
- Chapter 3: Drafting documentation
- Chapter 4: Editing documentation
- Chapter 5: Integrating code samples
- Chapter 6: Adding visual content
- Chapter 7: Publishing documentation
- Chapter 8: Gathering and integrating feedback
- Chapter 9: Measuring documentation quality
- Chapter 10: Organizing documentation
- Chapter 11: Maintaining and deprecating documentation
- Appendix A: When to hire an expert
- Appendix B: Resources
- Bibliography
- Index
فایل کتاب Docs for Developers را می‌توانید پس از پرداخت، دریافت کنید.
دیدگاهها
هیچ دیدگاهی برای این محصول نوشته نشده است.