مستندات نرم افزاری خوب ، چه مستندات مشخص برای برنامه نویسان و آزمایش کنندگان ، چه اسناد فنی برای کاربران داخلی ، چه کتابچه های راهنما و فایل های راهنما برای کاربران نهایی ، به کاربران در درک ویژگی ها و عملکردهای نرم افزار کمک می کند. مستندات خوب مستنداتی هستند که مشخص ، واضح و مرتبط با تمام اطلاعات مورد نیاز کاربر است. این مقاله شما را راهنمایی می کند تا اسناد نرم افزاری را برای کاربران فنی و کاربران نهایی بنویسید.
گام
روش 1 از 2: نوشتن مستندات نرم افزار برای کاربران فنی
مرحله 1. بدانید چه اطلاعاتی را باید شامل شود
سند مشخصات به عنوان راهنمای مرجع برای طراحان رابط ، برنامه نویسانی که کد می نویسند و آزمایش کننده هایی که عملکرد نرم افزار را تأیید می کنند ، استفاده می شود. اطلاعاتی که باید وارد شود بستگی به برنامه ایجاد شده دارد ، اما ممکن است موارد زیر را شامل شود:
- فایلهای مهم در برنامه مانند فایلهای ایجاد شده توسط تیم توسعه دهنده ، پایگاههای داده دسترسی یافته هنگام اجرای برنامه و برنامههای شخص ثالث.
- توابع و زیر روال ها ، شامل توضیح در مورد استفاده از تابع/زیر روال ، مقادیر ورودی و خروجی.
- متغیرها و ثابت های برنامه و نحوه استفاده از آنها
- ساختار کلی برنامه برای برنامه های مبتنی بر درایو ، ممکن است لازم باشد هر ماژول و کتابخانه را شرح دهید. یا اگر در حال نوشتن کتابچه راهنمای برای برنامه تحت وب هستید ، ممکن است لازم باشد توضیح دهید که هر صفحه از چه فایل هایی استفاده می کند.
مرحله 2. تصمیم بگیرید که چه سطحی از اسناد باید موجود باشد و از کد برنامه قابل تفکیک باشد
هرچه مستندات فنی بیشتری در کد برنامه گنجانده شود ، به روز رسانی و نگهداری آن و توضیح نسخه های مختلف برنامه آسان تر خواهد بود. حداقل ، اسناد موجود در کد برنامه باید شامل استفاده از توابع ، زیرروالها ، متغیرها و ثابت ها باشد.
- اگر کد منبع شما طولانی است ، می توانید اسناد را در یک فایل راهنما بنویسید ، سپس می توانید ایندکس شده یا با کلمات کلیدی خاصی جستجو شود. اگر منطق برنامه در چندین صفحه تقسیم شده و شامل فایلهای پشتیبانی مانند برنامه وب است ، فایلهای مستندسازی جداگانه مفید هستند.
- برخی از زبانهای برنامه نویسی (مانند جاوا ، Visual Basic. NET یا C#) دارای استانداردهای مستندسازی کد خود هستند. در چنین مواردی ، اسناد استاندارد را که باید در کد منبع گنجانده شود ، دنبال کنید.
مرحله 3. ابزار مستند سازی مناسب را انتخاب کنید
در برخی موارد ، ابزار اسناد با زبان برنامه نویسی مورد استفاده تعیین می شود. زبانهای C ++ ، C#، ویژوال بیسیک ، جاوا ، PHP و دیگر ابزارهای مستندسازی خود را دارند. با این حال ، در غیر این صورت ، ابزارهای مورد استفاده به اسناد مورد نیاز بستگی دارد.
- یک واژه پرداز مانند Microsoft Word برای ایجاد فایل های متنی سند مناسب است ، به شرطی که مستندات مختصر و ساده باشد. برای ایجاد اسناد طولانی با متن پیچیده ، اکثر نویسندگان فنی یک ابزار مستندسازی تخصصی مانند Adobe FrameMaker را انتخاب می کنند.
- فایلهای راهنما برای مستندسازی کد منبع را می توان با یک برنامه تولید کننده فایل پشتیبانی مانند RoboHelp ، Help and Manual ، Doc-To-Help ، MadCap Flare یا HelpLogix ایجاد کرد.
روش 2 از 2: نوشتن مستندات نرم افزاری برای کاربران نهایی
مرحله 1. دلایل کسب و کار را که زمینه ساز ایجاد دفترچه راهنما است ، بشناسید
در حالی که دلیل اصلی مستندات نرم افزاری این است که به کاربران در نحوه استفاده از برنامه کمک کند ، چندین دلیل دیگر وجود دارد که ممکن است زمینه ساز ایجاد اسناد باشد ، مانند کمک به بخش بازاریابی برای فروش برنامه ، بهبود تصویر شرکت و کاهش پشتیبانی فنی هزینه ها در برخی موارد ، مستندات برای رعایت مقررات یا سایر الزامات قانونی مورد نیاز است.
با این حال ، اسناد جایگزین مناسبی برای یک رابط نیست. اگر برنامه ای برای کار نیاز به اسناد زیادی دارد ، باید بصری تر طراحی شود
مرحله 2. مخاطبان اسناد را بشناسید
به طور کلی ، کاربران نرم افزار دانش رایانه ای فراتر از برنامه های مورد استفاده خود دارند. چندین روش برای برآوردن نیازهای اسناد آنها وجود دارد:
- به عنوان کاربر نرم افزار توجه کنید. به عنوان مثال ، مدیر سیستم به طور کلی برنامه های مختلف رایانه ای را درک می کند ، در حالی که منشی فقط برنامه هایی را که برای وارد کردن داده ها استفاده می کند می داند.
- به کاربران نرم افزار توجه کنید. اگرچه موقعیت های آنها به طور کلی با وظایف انجام شده سازگار است ، این موقعیت ها بسته به محل کسب و کار ممکن است حجم کاری متفاوتی داشته باشند. با مصاحبه با کاربران بالقوه ، می توانید بفهمید که ارزیابی شما از عنوان شغلی آنها صحیح است.
- به اسناد موجود توجه کنید. مستندات و مشخصات عملکرد نرم افزار می تواند آنچه کاربران باید برای استفاده از آنها بدانند را نشان دهد. با این حال ، به خاطر داشته باشید که کاربران ممکن است علاقه ای به دانستن "درون" برنامه نداشته باشند.
- بدانید که برای تکمیل یک کار چه چیزی لازم است و قبل از اینکه بتوانید آن را به پایان برسانید.
مرحله 3. قالب مناسب برای مستندات را تعیین کنید
اسناد نرم افزاری را می توان در 1 یا 2 فرمت ، یعنی کتابهای مرجع و کتابچه های راهنما تنظیم کرد. گاهی اوقات ، ترکیب دو قالب راه حل خوبی است.
- قالب های مرجع برای توصیف همه ویژگی های نرم افزار مانند دکمه ها ، برگه ها ، فیلدها و کادرهای گفتگو و نحوه عملکرد آنها استفاده می شود. برخی از فایل های راهنما با این فرمت نوشته می شوند ، به ویژه آنهایی که به زمینه حساس هستند. هنگامی که کاربر روی Help روی صفحه ای خاص کلیک می کند ، کاربر موضوع مربوطه را دریافت می کند.
- از قالب دستی برای توضیح نحوه انجام کاری با نرم افزار استفاده می شود. کتابچه های راهنما عموماً به صورت چاپی یا PDF هستند ، اگرچه برخی از صفحات راهنما همچنین شامل دستورالعمل هایی برای انجام برخی کارها هستند. (به طور کلی ، فرمت های دستی به زمینه حساس نیستند ، اما ممکن است از موضوعات حساس به زمینه مرتبط شوند). کتابهای راهنما عموماً به صورت راهنما هستند ، با خلاصه ای از وظایف که باید در توضیحات انجام شود و راهنمای فرمت شده در مراحل.
مرحله 4. درباره نوع اسناد تصمیم بگیرید
مستندات نرم افزاری برای کاربران ممکن است در یک یا چند قالب زیر بسته بندی شوند: راهنمای چاپ شده ، فایل های PDF ، فایل های راهنما یا راهنمای آنلاین. هر نوع مستندسازی به گونه ای طراحی شده است که نحوه استفاده از عملکردهای نرم افزار را نشان می دهد ، خواه راهنما باشد یا آموزشی. مستندات آنلاین و صفحات راهنما همچنین ممکن است شامل فیلم های نمایشی ، متن و تصاویر ثابت باشند.
فایلهای کمک و پشتیبانی آنلاین باید با استفاده از کلمات کلیدی فهرست بندی و جستجو شوند تا کاربران بتوانند به سرعت اطلاعات مورد نیاز خود را پیدا کنند. اگرچه یک برنامه ایجاد فایل راهنما می تواند یک فهرست را به طور خودکار ایجاد کند ، اما هنوز توصیه می شود که یک فهرست را به صورت دستی با استفاده از کلمات کلیدی معمولاً جستجو شده ایجاد کنید
مرحله 5. ابزار مستند سازی مناسب را انتخاب کنید
بسته به طول و پیچیدگی فایل ، کتابچه های راهنمای چاپی یا PDF را می توان با یک برنامه پردازش کلمه مانند Word یا یک ویرایشگر متن پیشرفته مانند FrameMaker ایجاد کرد. فایل های راهنما را می توان با یک برنامه ایجاد فایل راهنما مانند RoboHelp ، Help and Manual ، Doc-To-Help ، Flare ، HelpLogix یا HelpServer نوشت.
نکات
- متن اسناد برنامه باید به گونه ای تنظیم شود که خواندن آن آسان باشد. تصویر را تا آنجا که ممکن است نزدیک متن مناسب قرار دهید. به طور منطقی اسناد را بر اساس بخشها و موضوعات تقسیم کنید. هر بخش یا موضوع باید یک مشکل خاص را توضیح دهد ، هم وظیفه و هم ویژگی های برنامه. مسائل مرتبط را می توان با پیوندها یا لیست های مرجع توضیح داد.
- هر یک از ابزارهای اسناد توصیف شده در این مقاله را می توان با یک برنامه ساز عکس از صفحه (SnagIt) تکمیل کرد ، در صورتی که مستندات شما به چندین عکس از صفحه نیاز دارد. مانند هر اسناد دیگری ، شما همچنین باید اسکرین شات هایی را برای توضیح نحوه عملکرد برنامه ، به جای "جلب" کاربر ، اضافه کنید.
- توجه به سبک بسیار مهم است ، به خصوص اگر در حال نوشتن اسناد نرم افزاری برای کاربران نهایی هستید. کاربران را به جای "کاربر" با ضمیر "شما" خطاب کنید.
