این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه ی پروژه
- سازمان منبع باز:
- SciPy
- نویسنده فنی:
- mkg33
- نام پروژه:
- مستندات کاربر محور و بازسازی کامل
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
انگیزه:
من قصد دارم روی بازسازی اسناد موجود کار کنم تا کاربران با نیازهای مختلف به راحتی در دسترس باشند. ناگفته نماند که یک محقق به احتمال زیاد به ویژگی های پیشرفته و ظریف علاقه مند است، در حالی که کاربر بدون تخصص قبلی از راهنماها و نمودارهای گام به گام قدردانی می کند.
من علاقه مند به دنبال کردن این پروژه به دلایل شخصی و حرفه ای هستم: اول از همه، من می خواهم به طور قابل توجهی به SciPy کمک کنم زیرا تحقیقات خود من از آن سود زیادی برده است و ثانیاً، من اغلب با اسناد ناکافی (یا کمبود) در سایر موارد روبرو هستم. نرم افزار و همیشه از خود می پرسد که اگر راهنمای کاملی برای کاربران ارائه شده باشد، چقدر سریع تر (اگر همه چیز!) می توانند نحوه استفاده از کد را یاد بگیرند.
اهداف:
هدف من بهبود اسناد SciPy موجود هم از نظر محتوا و هم از نظر گرافیکی است. مهمترین ویژگی رویکرد من به این مشکل، استقرار و تجزیه و تحلیل نظرسنجی کاربران است، یعنی یک نظرسنجی مختصر که به صورت آنلاین انجام می شود و کاربران مختلف را قادر می سازد تا نیازهای خود را در مورد مستندات بیان کنند. من قویاً معتقدم که نظرات آنها باید منبع الهام باشد (چگونه می توانیم اسناد کاربرپسندتری ایجاد کنیم؟).
با توجه به تحقق خود پروژه، مرحله اول شامل طراحی و تجزیه و تحلیل نظرسنجی کاربران و همچنین رسیدگی به چندین موضوع سبکی است که در مستندات فعلی متوجه شده ام. به عنوان مثال، عدم هماهنگی (مثال: آرایه‌های دو بعدی که در کنار آرایه‌های دوبعدی قرار می‌گیرند)، جملات پیچیده‌ای که باید بازنویسی شوند، یا عدم ترتیب الفبا در صفحات فرعی خاص. مرحله دوم بر معرفی راهنماهای گرافیکی حاوی لینک های فوق به موضوعات مربوطه (بر اساس نتایج نظرسنجی و سایر درخواست های جامعه) تمرکز خواهد کرد. در درازمدت، من آرزو دارم به یک مستندات رضایت بخش متناسب با انواع مختلف کاربران دست پیدا کنم. علاوه بر این، من سعی خواهم کرد که آموزش ها را هم از نظر زبانی و هم از نظر ساختاری سازگارتر ارائه کنم. در نهایت، هدف من نوشتن آموزش های جدید (بر اساس نیازهای فعلی جامعه) است.
نظرسنجی کاربران:
در مورد نظرسنجی کاربران، من پیشنهاد می کنم به دلایل مختلفی از Google Forms استفاده کنید. اول از همه، Google Forms رایگان است و عملکرد نامحدودی را ارائه می دهد (از نظر تعداد پاسخ دهندگان، سؤالات و غیره)، دارای یک فرم بصری جذاب، مفیدترین گزینه های نظرسنجی (به عنوان مثال، مقیاس خطی قابل تنظیم، چک باکس ها، و چند گزینه ای)، و از همه مهمتر، نتایج را می توان به راحتی برای اهداف تجزیه و تحلیل آماری صادر کرد. بر اساس تحقیقات آنلاین، به نظر می رسد که Google Forms، حداقل در حال حاضر، بهترین ابزار رایگان برای انجام نظرسنجی است. در یک نکته نه چندان جدی، استفاده از یک محصول Google در ابتکاری که توسط Google انجام می شود، حرکت خوبی خواهد بود.
من یک نظرسنجی مقدماتی با نمونه سوالات ایجاد کرده ام (در https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform قابل دسترسی است). تعداد معقول سوالات در نسخه نهایی باید بین ده تا پانزده سوال باشد. برای به دست آوردن نتایج ملموس، من پیشنهاد می کنم که عمدتاً از سؤالات چند گزینه ای، مقیاس خطی و چند چک باکس استفاده کنیم. مقیاس خطی نباید به یک طیف کامل شباهت داشته باشد (تنها باعث سردرگمی می شود و نتایج احتمالاً از پراکندگی بالایی رنج می برند). حداکثر باید دو سوال با پایان وجود داشته باشد، در غیر این صورت نتایج بسیار پراکنده خواهند بود و به هیچ وجه مفید نیستند. من فکر می کنم که حتی تعداد بسیار بالایی از پاسخ ها نیز مشکل ساز نخواهد بود، زیرا داده ها به راحتی می توانند به طور خودکار با نرم افزار آماری صادر و تجزیه و تحلیل شوند. با فرض اینکه تعداد پاسخ ها واقعاً بسیار زیاد است، تجزیه و تحلیل سؤالات باز می تواند کمی وقت گیر باشد، اما من فرض می کنم که طاقت فرسا نخواهد بود. از این گذشته، یک کاربر معمولی احتمالاً مقاله ای در مورد وضعیت اسناد بنویسد. در بدترین حالت، برخی از پاسخ ها را می توان به سادگی برای تجزیه و تحلیل آینده ذخیره کرد.
راهنمای گرافیکی:
دیدگاه من از راهنماهای گرافیکی (در نظر گرفته شده برای خدمت به عنوان ابزار ناوبری) بر اساس یک فرض رایج است که (بیشتر) انسان ها در پردازش ساختارهای بصری ساده به جای اطلاعات صرفاً مبتنی بر متن بهتر هستند. علاوه بر این، یک نمودار موضوعی با خطوطی که موضوعات مشابه مورد علاقه را به هم متصل می کند، بدون شک دارایی بسیار ارزشمندی برای کاربران کمتر با تجربه (و نه تنها) است.
با توجه به جزئیات پیاده سازی، من پیشنهاد می کنم از بسته TikZ استفاده کنید. اول و مهمتر از همه، این ابزار قدرتمندی است و به نظر نمی رسد که به زودی در معرض خطر منسوخ شدن قرار گیرد. همچنین خروجی با کیفیت بالا ارائه می دهد، مستندات واقعاً محکمی دارد و موضوعی رایج در TeX StackExchange و دیگر انجمن های اصلی است. مهمتر از همه، ادغام یک فایل TikZ (به طور دقیق تر، لینک های متعدد موجود در آن) با مستندات HTML به نظر نمی رسد به دلیل وجود بسته ها و راه حل های مختلف برای جاسازی یک تصویر TikZ در HTML (به عنوان مثال، TeX4ht) مشکلات قابل توجهی ایجاد کند. .
مسئله نگهداری راهنماها در آینده در SciPy را می توان به راحتی با استفاده از مثلاً Overleaf (همکاری را تسهیل می کند و یک پیش نمایش فوری ارائه می دهد) و الگوهای از پیش تعریف شده ای که من ارائه خواهم کرد، حل می شود. اساساً، راهنماهای گرافیکی احتمالاً تفاوت زیادی با یکدیگر ندارند. ساختار، پالت رنگ و اشکال کم و بیش ثابت خواهند بود، بنابراین شکل دهی مجدد بعدی و سفارشی سازی بیشتر مشکلی نخواهد بود.
(لطفاً نسخه کامل پیشنهاد - موجود در پوشه مشترک GSoD را ببینید.)