مستندسازی از دیدگاه اغلب برنامه‌نویسان و توسعه‌دهندگان نرم‌افزار، کاری کسل‌کننده و تلف‌کننده‌ی وقت است، اما در واقع مستندسازان متبهر و دست‌به‌قلم نقشی بسیار مهم‌تر از اعتباری که به آن داده شده بازی می‌کنند.
مستندسازی از دیدگاه اغلب برنامه‌نویسان و توسعه‌دهندگان نرم‌افزار، کاری کسل‌کننده و تلف‌کننده‌ی وقت است، و با آن به عنوان کم ارزش‌ترین جزء چرخه‌ی توسعه‌ی نرم‌افزار برخورد می‌کنند. اما در واقع مستندسازان متبهر و دست‌به‌قلم نقشی بسیار مهم‌تر از اعتباری که به آن داده شده بازی می‌کنند. با توجه به پاسخ‌های متداول به سؤالات کاربران، پشتیبانی از مستنداتی همانند، راهنمای کاربران یا فهرست تقلب‌های فنی، هم برای کاربران و هم برای توسعه‌دهندگان مزایایی را به همراه دارد. به کاربران فرصت دریافت کارایی و خدمات بیشتر را از آنچه خریداری کرده‌اند می‌دهد و همچنین هزینه‌های توسعه‌دهندگان را برای پشتیبانی بعد از فروش کاهش می‌دهد.
اگر شغل شما مرتبط با مستندسازی برای برنامه های نرم‌افزاری است، پس تهیه‌ی یک فهرست و فرآیند ساده برای هدایت فعالیت‌ها، فکری بسیار پسندیده است. این ۶ قدم مثالی برای تهیه‌ی چنین فهرستی است. دفعه‌ی بعد که قصد نوشتن یک راهنمای نرم‌افزار و مستند نیازمندی داشتید، حتماً از این‌ها استفاده کنید.
۱٫ درک مخاطبین:
یکی از مهم‌ترین مسائلی که به شما در بهبود مستندات کمک می‌کند، دریافت درک مناسبی از مخاطب مستند است. کشف آمار دقیق کاربران از نظر سن، سطح مهارت در نرم‌افزار، قصد آنها از بکارگیری نرم‌افزار و مشکلات رایجی که با آنها دست و پنجه نرم می‌کنند، امری ضروری است. بعد از دریافت چنین دانش و اطلاعاتی می‌توانید درباره‌ی سطح مهارت مستندتان تصمیم‌گیری نمایید؛ لحن و زبان گویش، عمق مطالبی که می‌بایست عنوان گردد و مقیاس‌هایی که مناسب مستند می‌باشد.
مثال: مستندات کاربری یک بسته حساب‌داری به طوری چشم‌گیری بسته به مخاطب آن از یک کاربر ساده‌ی خانگی تا یک کاربر حرفه‌ای، متفاوت است. برای دومی ممکن است مفاهیم ابتدایی نادیده گرفته شود و مسائل حرفه‌ای و اساسی در سطح گسترده‌‌ای مورد بحث قرار گیرد و برای اولی رهیافتی معکوس مناسب‌تر است.
۲٫ تعیین حوزه
پس از شناخت مخاطب، نوبت به تعریف حوزه‌ی مستندتان می‌رسد. فهم واضح هدف مستندتان و گستره‌ی اهدافی که قصد رسیدن به آن را دارد، بسیار حائز اهمیت می‌باشد. به هنگام تعیین حوزه، عواملی همچون مهارت فعلی کاربر، بستره‌ی سخت‌افزاری و نرم‌افزاری که قرار است بحث شود، سطح اطلاعات مورد نیاز برای عیب‌یابی، میزان جزئیات فنی مناسب برای گروه کاربران علاقه‌مند، را مدنظر داشته باشید. این‌ها سؤالات بزرگی است و تعریف حوزه‌ی مستندتان هم کار کوچکی نیست و نیازمند شناختی شفاف و واضح از مخاطب به همراه سطح دانش آنها است.
مثال: یک مرجع راهنمای فنی برای فروشندگان نرم‌افزار کارت گرافیکی، جزئیاتی درباره‌ی رابط‌های برنامه‌نویسی را در بر خواهد داشت، اما اطلاعاتی راجع به فرآیند نصب فیزیکی را ارائه نمی‌کند.
۳٫ تعریف قراردادهای قالب و شمایل مستند
پس از آن که مخاطبین و حوزه مشخص گردید، نوبت به صرف اندکی زمان برای تعریف قالبِ مستند می‌رسد. این مرحله کار سازمان‌دهی و قالب‌بندی اطلاعات را در مراحل بعد آسان می‌کند. مسلماً شما می‌بایست تصمیم به استفاده از سرفصل و زیرمجموعه‌ی آن، قالبی برای انواع مختلف متون و قرارداد نام‌گذاری برای جداول، نمودارها و تصاویر، اتخاذ کنید. همچنین ظاهر اجزاء صفحه همانند عناوین بخش‌ها، سربرگ صفحه، پاصفحه و شماره‌ی صفحه را در این مرحله مشخص می‌کنید.
مثال: بسیاری از مستندات از جداول برای ارائه‌ی اطلاعات در روشی ساخت‌یافته، بهره می‌جویند. یکی از روش های متدوال برای شماره‌گذاری جداول، استفاده از ترکیب فصل و شماره‌ی جدول است. برای مثال نام جدول ۴-۱۵ بیان‌گر چهارمین جدول فصل ۱۵ است.
۴٫ ایجاد پیش‌نویس فهرست مطالب
ایجاد یک پیش‌نویس از فهرست مطالب مستند در مراحل اولیه، کار بسیار نیکویی است، زیرا به شما امکان تعیین گستره‌ی عناوین و سرفصل‌ها را می‌دهد. سپس می‌توانید به دسته‌بندی داده‌ها در قسمت‌های مختلف به پردازید و به همراه آن، اطلاعات ناخواسته را از فهرست تصفیه نمایید. در حالی کهدر این مرحله عناوین اطلاعات از یک بخش به بخش دیگر تغییر می‌کند، می‌توانید هر یک با خلاصه و چکیده‌ای شروع کنید که شامل هدف مستند، قراردادهای مورد استفاده، واژه‌نامه اصلاحات و در انتها با اطلاعات عیب‌یابی و/یا فهرست ضمیمه‌های حاوی داده‌های فنی جزء که در فضای عادی این مستند نمی‌گنجد، به پایان برسانید.
مثال: عنوان متداول برای راهنمای کاربری می‌تواند، معرفی، نصب، کاربری، مدیریت، عیب‌یابی، ضمیمه‌ها و نمایه باشد.
۵٫ نهایی کردن فهرست مطالب، شروع ایجاد مستند
پس از ایجاد پیش‌نویس فهرست مطالب، تمام فکر و ذهنتان را بر روی جمع‌اوری تمام اطلاعاتی که برای ایجاد مستند نیاز دارید، متمرکز کنید. به هنگام جمع‌آوری داده‌ها، آنها را با توجه به پیش‌نویس فهرست، امتحان و بازآزمایی کنید تا اطمینان حاصل کنید که “جایی برای هر چیز هست و هر چیز جایی دارد”. حتماً باید زیرعنوان‌های پیش‌نویستان را برای اصلاح هر چه بهتر خزئیات اطلاعاتی، تغییر دهید؛ این امری طبیعی است و در جدول زمان‌بندی‌تان هم می‌بایست برنامه‌ای برای آن داشته باشید. پس از سازمان‌دهی همه‌ی اطلاعات و نهایی کردن فهرست مطالب، کار اصلی برای تولید محتوا آغاز می‌شود.
مثال: برای بهبود دسترسی به بخش عیب‌یابی، بسیاری از راهنماهای کاربری، در این بخش به زیربخش‌هایی همانند، مشکلات نصب، مشکلات راهبری و مشکلات مدیریتی، تقسیم‌بندی شده‌اند. این نکته را برای مستند خودتان نیز مدنظر داشته باشید.
۶٫ انجام بازنگری فنی و کاربری
بعد آن که فهرست مطالب را نهایی کردید، تمامی محتویات لازم ایجاد نمودید، قالب‌بندی را همان‌گونه از قبل انتظار می‌رفت، طبق قراردادها، انجام دادید و براساس طرح اولیه با توجه به مخاطب و حوزه‌ی مورد نظر، بازنگری نمودید، اکنون زمان آن فرارسیده است که با نگاهی تیزبین، مطالب را بررسی نمایید. مطلوب آن است که این چشمان، به یک یا تنی چند از از مخاطبین نهایی تعلق داشته باشند، زیرا اینان در بهترین جایگاه، برای اعمال نظر در مورد پوشش نیازمندی‌هایشان، که مستند به آنها اشاره دارد، قرار دارند.
مثال: یک مثال از فهرست تقلب‌های فنی برای یک بازنگری فنی ممکن است شامل نکات ریزی همانند “حصول اطمینان از صحت دیکته‌ی اسامی APIها” و “بررسی مقادیر بازگشتی هر تابع”، باشد.
منبع: TechRepublic
دیدگاه ها