توسعه نرم‌افزارهای متن باز ( مستندات پروژه)

مستندات پروژه (Project Documentation)
علاوه بر مستندات مورد نیاز برای یک کاربر نهایی (که به صورت معمول در پروژه های نرم افزاری وجود دارد)، یک پروژه متن باز نیاز دارد که مستندات داخلی خوبی هم برای توسعه دهندگان داشته باشد. شما باید این مستندات را تا حد ممکن ساده تهیه کنید تا توسعه دهندگان جدید بتوانند به راحتی ساختار کد منبع را درک کنند. این کار موجب می شود که توسعه دهندگان جدید به راحتی کارشان را شروع کنند و توسعه دهندگان بیشتری برای همکاری، ترغیب می شوند. عدم وجود یا ضعیف بودن مستندات داخلی موجب می شود که توسعه دهندگان تمایل به قطع کردن همکاری پیدا کنند.
برای توسعه دهندگانی که کار بر روی پروژه را به عنوان بخشی از کار معمول روزانه شان انجام می دهند، اختصاص دادن زمان کافی جهت درک ساختار و نحوه کارکرد کد پروژه امری طبیعی و قابل قبول است. برای این اشخاص ضعیف بودن مستندات امری عادی است، اما برای افرادی که فقط بخش کمی از زمان آزادشان را به توسعه پروژه، اختصاص می دهند و می خواهند خطایی را اصلاح کنند یا تغییر خیلی کمی اعمال کنند، کیفیت مستندات می توانند نقش خیلی مهمی در موفقیت یا شکست آنها داشته باشد. توسعه دهندگان جدید نیاز دارند که بتوانند رابطه های موجود در کد منبع را درک کنند و به اندازه کافی در مورد نحوه کار کد پروژه اطلاعات کسب کنند، تا بتوانند تغییرات مورد نظرشان را درآن اعمال کنند. اگر آنها در ابتدا بتوانند با موفقیت تغییرات مورد نظرشان را اعمال کنند به انجام کارهای بیشتر بر روی کد علاقمند تر خواهند شد. یک ابزار مبتنی بر web که می تواند به توسعه دهندگان جهت جستجو در کد منبع کمک کند، lxr است. این به این معنی است که همه توسعه دهندگانی که در کد منبع همکاری دارند باید مستندات مربوط به کد خودشان را تهیه کنند. اشخاص اغلب نیاز دارند که مستندات مربوط به طراحی را نوشته و ضرورتا آنها را به روز نگه دارند و همچنین توضیحات سطح بالایی در مورد معماری نرم افزار تهیه کنند. این موضوع می تواند یک کار اضافه برای کسانی باشد که در پروژه شما مسئولیت نوشتن مستندات تکنیکی را بر عهده دارند.
Mailing list معمولا یک مکان خوب برای توسعه دهندگان جدید (و قدیمی) است که می خواهند از تصمیمات مختلف طراحی اطلاع داشته باشند.
مستندات مهم دیگری که باید وجود داشته باشد، نقشه مسیر(road map) پروژه است. نقشه مسیر پروژه، برنامه توسعه را برای کل پروژه و برای پیمانه ها به صورت اختصاصی توضیح می دهد. نقشه مسیر تعیین می کند که برنامه توسعه دهندگان هسته (تیم مدیریت پروژه) و مسئولان پیمانه ها، در بحثهای داخل mailing list چیست. نقشه مسیر این امکان را به توسعه دهندگان و کاربران می دهد که بتوانند از تغییراتی که در پروژه انجام خواهد شد و زمان اعمال این تغییرات اطلاع پیدا کنند. بسیاری از توسعه دهندگان با استفاده از نقشه مسیر تصمیم می گیرند که چه کاری را باید انجام بدهند. پس این حیاتی است که نقشه مسیر به روز نگه داشته شود. نقشه مسیر و جلسات مذاکره هستند که مسائلی مانند ویژگی هایی (Features) که باید در پروژه موجود باشند، راهنماهای مورد نیاز برای تمرکز بر روی پروژه و جهت گیری پروژه را تعیین می کنند. شما اغلب نیاز دارید که لیست های دلخواه (wish list) را برای کل پروژه و یا برای هر پیمانه خاص تهیه کنید.
لیست دلخواه مکان مناسبی برای توسعه دهندگان است که می توانند از طریق آن بفهمند که چه موقع آنها می توانند کار مورد علاقه شان را برای کمک به انجام پروژه انجام دهند (به عنوان مثال چه موقع لازم است که پیمانه خاصی که مورد علاقه توسعه دهنده است پیاده سازی شود.) فرآیند ایجاد لیست دلخواه، کاربران را به صحبت کردن و شرکت در طراحی تشویق می کند. مشارکت کاربران به عنوان طراح در موفقیت واقعی پروژه نقش خیلی مهمی دارد.
کاربران نهایی شما هم اغلب نیاز به مستندات دارند. این احتمال وجود دارد که تعدادی از کاربران تمایل داشته باشند که در نوشتن این مستندات کمک کنند. Mailing list عمومی کاربران یک منبع اطلاعاتی عالی است. سازمان دهی اطلاعات در درون یک لیست مرتبط از سوالات پرسیده (FAQ) اولین قدم مناسب است.
اگر شما نویسندگان فنی و حرفه ای دارید که در پروژه شما کار می کنند، آنها می توانند مسئول مستندات پیمانه ها باشند، در این حالت دیگران می توانند پیشنهادات و اطلاعات خود را برای آنها ارسال کنند، اما آنها هستند که تصمیم می گیرند که چه چیزهایی در مستندات قرار گیرد. البته اگر یک کدنویس پیمانه، تعدادی پیشنهاد خوب ارائه دهد، می تواند این حق را پیدا کند که مستقیما مستندات را ویرایش کند. مستندات باید طوری آماده شوند (درقالبی باشند) که اشخاص بتوانند به سادگی آنها را بخوانند، مثلا به صورت text یاHTMailing list باشند و نیازی نباشد که کاربران و توسعه دهندگان برای خواندن مستندات، نرم افزار خاصی را در اختیار داشته باشند (مخصوصا نرم افزارهایی که برای تهیه آنها باید هزینه پرداخت شود).
چند پروژه متن باز برای استاندارد سازی DocBook/xMailing list به عنوان قالب متعارف برای مستندات نرم افزارهای متن باز مطرح شده اند.