مستند سازي نرم افزار

1. مستند سازي نرم افزار درس شيوه ارائه مطالب علمي بصير شريعت رضوي حسين بشاشتي

2. عناوين • انواع مستندسازي • اهميت مخاطب • اهميت انتخاب لغت و سازگاري • اهميت ساختار • اهميت فهرست • اهميت ويرايش و بازبيني • ابزارهاي موجود • ... دانشکده فني - دانشگاه تهران

3. انواع مستند سازي • مستند سازي براي سطوح متفاوتي از نرم افزار • مستند سازي مشخصات سيستم براي استفاده (درون سازماني) • مستند سازي زير بخشهاي مشترک براي تعيين قالب ها (درون سازماني) • مستند سازي برنامه براي کاربرهاي مياني (درون سازماني) • ... • مستند سازي نرم افزار براي کاربر نهايي • موفقيت يک پروژه ارتباط مستقيمي با سطح پشتيباني از نيازها و خواسته هاي کاربر نهايي دارد دانشکده فني - دانشگاه تهران

4. اهميت مخاطب مستند • مخاطب مهمترين عنصر در يک مستند سازي موفق • وظيفه اصلي يک مستند : انتقال اطلاعات لازم به مخاطب • بايد دقيقا بدانيد : • اطلاعات قبلي مخاطب • اطلاعات مورد نياز مخاطب • بهترين و سريعترين راه انتقال اطلاعات به کاربر • عدم شناخت دقيق مخاطب بزرگترين تهديد براي يک مستند است. دانشکده فني - دانشگاه تهران

5. اهميت انتخاب لغت و سازگاري • يک مستند سلسله مراتبي از دستورات است که مخاطب را براي انجام يک کار در سيستم راهنمايي مي کند. پس متن مستند بايد : • دقيق و خالي از هرگونه ابهام • کوتاه و توصيفي • خالي از غلط • سازگار از نظر لغوي • سازگار از نظر معنايي • و ... باشد دانشکده فني - دانشگاه تهران

6. اهميت ساختار • در دستورالعمل : • توضيح کامل نتيجه کاري که مخاطب انجام مي دهد قبل از دستورالعمل • رعايت ترتيب منطقي قدم ها • عدم حذف هيچکدام از قدم ها (حتي قدم هاي خيلي کوتاه و ساده) • در متن مفهومي : • اعلان پيش نيازهاي هر مطلب جديد • توضيح مطالب ابتدايي پيش از پرداخت به مطالب پيشرفته • خود را جاي مخاطب خود بگذاريد و مثل او فکر کنيد ! دانشکده فني - دانشگاه تهران

7. اهميت فهرست • اکثر کاربران در اولين قدم به فهرست مستند رجوع مي کنند تا مطلب مورد نظر خود را پيدا کنند. • بنابراين شما بايد مطمئن باشيد که مخاطب با عدم آگاهي از واژه دقيق اطلاعات مورد نياز خود را پيدا مي کند ! دانشکده فني - دانشگاه تهران

8. اهميت ويرايش و بازبيني • مستند بعد از نوشتن آخرين کلمه تمام نمي شود ! • وظيفه ويرايشگر : • بررسي گرامر ، املا لغات ، سازگاري لغوي و سازگاري ساختاري • وظيفه بازبين (معمولا يکي از توسعه دهندگان) : • بررسي دقت دستوالعمل ها و مفاهيم • بررسي تغييرات اعمال شده در سيستم در حين فرآيند توسعه دانشکده فني - دانشگاه تهران

9. ارزيابي مخاطب Over time, quality work will lead to an audience for your work. دانشکده فني - دانشگاه تهران

10. شناخت مخاطب • اولين منبع براي شناخت دقيق مخاطب بررسي خود نرم افزار است. • شناخت مخاطب با مشاوره با مدير محصول • مدير محصول معمولا يک ديد انتزاعي از محصول دارد • اِعمال تحليل مخاطب به مستند • بررسي واژه شناسي مخاطب و تعريف واژه ها در صورت نياز • ساختار دهي به مستند جوري که براي کاربر معني دار باشد • چه اتفاقي مي افتد اگر مخاطب خود را اشتباه بشناسيم ؟ • هر بخش را براي چه کسي مي نويسيم ؟ • تغييرات هنگام تهيه مستند. • واگرايي مخاطبان دانشکده فني - دانشگاه تهران

11. انتخاب کلمات و سازگاري Consistency and orthogonality are tools of design, not the primary goal in design. دانشکده فني - دانشگاه تهران

12. انتخاب کلمات و سازگاري • تمرين کنيد لغت درست را انتخاب کنيد • براي بعضي مفاهيم يک واژه شناخته شده در صنعت وجود دارد ! (Whamboozle Vs Widget) • ساده و روان • مراجعه به لغتنامه هاي مخصوص واژگان دامنه • از جملات معلوم و کوتاه استفاده کنيد. • لغات اضافي را حذف کنيد • در طول مستند از يک صدای يکتا استفاده کنيد ! • شکل سازگار در همه مستند دانشکده فني - دانشگاه تهران

13. انتخاب کلمات و سازگاري (ادامه) • از قالب سازمان خود برای حالت پيروی کنيد (علامت گذاری ، قالب و ...) • يک قالب مشخص برای خود و همکارانتان تعريف کنيد. • حفظ سازگاری در پروژه های چند نفره دانشکده فني - دانشگاه تهران

14. انتخاب کلمات و سازگاري (ادامه) • از قالب سازمان خود برای حالت پيروی کنيد (علامت گذاری ، قالب و ...) • يک قالب مشخص برای خود و همکارانتان تعريف کنيد. • حفظ سازگاری در پروژه های چند نفره دانشکده فني - دانشگاه تهران

15. روال ها و دستورالعمل ها One has to respect legal procedure. دانشکده فني - دانشگاه تهران

16. دستورالعمل ها • دستور العمل خوب به کاربر می گويد که در هر قدم چه کاری بکند نه اينکه در آينده چه خواهد کرد يا در گذشته چه کرده است. • دستورالعمل بايد به کاربر بگويد که چه کاری را چگونه انجام دهد. • از عبارات و جمله های کوتاه استفاده کنيد. • از هرگونه توضيح در طول دستورالعمل بپرهيزيد. • از ليست های مرتب استفاده کنيد. • از قانون هر خط يک دستور استفاده کنيد. • سازگار باشيد • همه نام هايي را که استفاده می کنيد در يک پايگاه داده ذخيره کنيد. دانشکده فني - دانشگاه تهران

17. دستورالعمل ها (ادامه) • کارهايي را که توصيف می کنيد خودتان انجام دهيد. • يک راه مطمئن برای دادن دستور العمل های غلط به مخاطب اتکا به حافظه خودتان است ! • اگر راه های مختلفی برای انجام يک کار وجود دارد آنها را به کاربر ياد دهيد. • هيچ قدم بديهی ای وجود ندارد ! باور کنيد ! دانشکده فني - دانشگاه تهران

18. استفاده از جدول ها و اشکال There are already a lot of devices in our lives that have rich text or the ability to handle graphics. Our devices are designed to be understood in less than a quarter of a second. دانشکده فني - دانشگاه تهران

19. جداول و اشکال • گاهی اوقات يک شکل يا يک جدول اطلاعات را خيلی بهتر به مخاطب انتقال مي دهد. • هنگامی که مفاهيمی که با هم مقايسه می شوند داراي ويژگی هايي هستند که از لحاظ منطقی بر هم عمود هستند از جداول استفاده کنيد. • استفاده از ScreenShot می تواند به مخاطب کمک کند تا بداند با چه چيزی مواجه مي شود. • زياد از ScreenShot استفاده نکنيد. • استفاده از ScreenShot برای ساختن واژه نامه. دانشکده فني - دانشگاه تهران

20. جداول و اشکال (ادامه) • استفاده از اشکال گرافيکی به همراه مشخص کردن معنای هر بخش به درک مسائل مفهومی کمک می کند. • نوشتن عناوين برای اشکال بايد جوری باشند که به مفهوم اصلی آنها اشاره کنند و به مخاطب بگويد که هنگام نگاه کردن به آنها بايد به چه چيزی فکر کند. • جدولِ جدول ها و جدول اشکال می تواند به مخاطب بگويد که کدام مفاهيم از همه مهمتر هستند. دانشکده فني - دانشگاه تهران

21. مراجع • [1] Michael E. Fagan. Design and code inspections to reduce errors in program development. IBM SystemsJournal, 15(3):182–211, 1976. • [2] Jesús M. González-Barahona, Miguel A. Ortuño Pérez, Pedro de las Heras Quirós, José Centeno González, and Vicente Matellán Olivera. Counting Potatoes: The Size of Debian 2.2. Upgrade, II(6):60–66, December 2001. • [3] Alexander Hars and Shaosong Ou. Why is open source software viable? A study of intrinsic motivation,personal needs, and future returns. In Proceedings of the Sixth Americas Conference on Information Systems (AMCIS 2000), pages 486–490, Long Beach, California, 2000. • [4] James Howison and Kevin Crowston. The perils and pitfalls of mining Source-Forge. In Proceedings ofthe International Workshop on Mining Software Repositories (MSR 2004), pages 7–11, Edinburgh, UK, دانشکده فني - دانشگاه تهران