فصل اسناد (Season of Docs) یک برنامه پایداری است که توسط دفتر برنامههای متنباز گوگل (Google Open Source Programs Office) مدیریت میشود. اهداف فصل اسناد عبارتند از:
- ارائه پشتیبانی برای پروژههای متنباز جهت حل مشکلات پروژه در زمینه مستندسازی
- به نویسندگان فنی فرصت دهید تا در زمینه متنباز تجربه کسب کنند
- افزایش آگاهی در مورد متنباز، مستندسازی و نگارش فنی
- جمعآوری و به اشتراکگذاری اطلاعات در مورد معیارهای مؤثر در مستندات متنباز
اطلاعات بیشتر در مورد برنامهی «فصل مستندها» در وبسایت این برنامه موجود است.
مرور کلی برنامه ۲۰۲۲
نحوه کار فصل اسناد
در فصل مستندسازی، سازمانها با ارسال یک طرح پیشنهادی برای پروژه اقدام میکنند. طرح پیشنهادی شامل موارد زیر است:
- اطلاعات مربوط به سازمان
- شرح مشکلی که پروژه با آن مواجه است
- چگونه پروژه از مستندات برای کمک به حل مشکل خود استفاده خواهد کرد
- چگونه پروژه اثربخشی مستندات خود (معیارها) را اندازهگیری خواهد کرد
- جدول زمانی برای انجام کار
- بودجه یک پروژه
- هرگونه اطلاعات اضافی، مانند تجربه سازمان در برنامههای مشابه، یا هر چیز دیگری که به مدیران فصل اسناد کمک کند تا پروژه و مشکل خود را درک کنند.
پس از پذیرش در این برنامه، سازمانها مستقیماً نویسندگان فنی خود را جذب و استخدام میکنند. سیزن آو داکز از اوپن کالکتیو برای تأمین مالی سازمانها استفاده میکند و سازمانها از طریق اوپن کالکتیو به نویسندگان فنی حقوق میدهند. بودجه و پرداختهای پروژه شفاف هستند؛ بودجهها در پیشنهادهای پروژه سازمان که در سایت سیزن آو داکز موجود است، گنجانده شدهاند و پرداختها در حساب سیزن آو داکز اوپن کالکتیو قابل مشاهده هستند.
سازمانها زمانی که گزارش مطالعه موردی خود را ارائه دهند، برنامه را با موفقیت به پایان رساندهاند. همچنین از سازمانها خواسته میشود که در طول برنامه، ارزیابیهای ماهانه و در طول سال پس از اتمام برنامه، سه نظرسنجی پیگیری فصلی انجام دهند.
نکات برجسته ۲۰۲۲
«پس از انتشار سند جدید، بازدیدهای روزانه از Casbin و Casdoor تقریباً دو برابر شد و نرخ پرش حدود 30 درصد کاهش یافت.» — Casbin
«یکی از نتایج لذتبخش این پروژه، تماشای تبدیل شدن [نویسندگان فنی ما] به نقشهای رهبری در جامعه ما بوده است. هر دو مشارکتکننده اکنون رهبری جلسات گروههای کاری و جامعه را بر عهده دارند و همچنین در طراحی و نگهداری پروژههای ما مشارکت دارند.» —moja-global
«[GSoD] به ما کمک کرد تا دو نویسنده فنی بااستعداد را استخدام کنیم که در یک مجموعه منظم بسیار دشوار است، و آنها همچنان مشارکتکنندگان فعال سیستمعامل در OpenMined هستند و ما با آنها تجربه کاری بسیار خوبی داشتهایم.» —OpenMined
«همچنین، این راهنمای جدید برای تازهکاران طیفسنجی جرمی محاسباتی بسیار آسانتر است. برای روشن شدن این نکته: کمکهزینه CZI همچنین برای افراد محروم از نظر تاریخی کمکهزینه تحصیلی فراهم میکند و برخی از دریافتکنندگان جایزه از راهنمای جدید OpenMS برای شروع دوره کارآموزی شش هفتهای خود استفاده کردهاند و نظرات مثبتی در مورد راهنمای جدید ارائه دادهاند.» —OpenMS
خلاصه دادهها ۲۰۲۲
در سال ۲۰۲۲، برنامهی «فصل مستندها» ۳۱ پروژه از ۶۷ درخواست را پذیرفت و ۳۰ پروژه با موفقیت برنامه را به پایان رساندند. از ۳۱ سازمان پذیرفتهشده، ۱۷ سازمان متقاضی تکراری بودند.
۳۱ پروژه پذیرفتهشده، ۵۸ نویسنده فنی را استخدام کردند. بیش از ۱۹۰ نویسنده فنی با افزودن اطلاعات تماس و لینک نمونه کارهای خود در مخزن گیتهاب Season of Docs، علاقه خود را به شرکت در این برنامه نشان دادند.
برای برنامه ۲۰۲۲:
- ۱۰۰٪ سازمانها تجربه مثبتی از فرآیند درخواست داشتند
- ۱۰۰٪ سازمانها تجربه مثبتی با مستندات/محتوای وبسایت برنامه داشتند.
- ۹۳٪ از سازمانها تجربه مثبتی با این برنامه داشتند
- ۹۰٪ سازمانها احساس کردند که پروژه مستندسازی آنها موفقیتآمیز بوده است.
درباره سازمانها
سازمانهای شرکتکننده در فصل اسناد ۲۰۲۲، طیف متنوعی از پروژههای متنباز را نمایندگی میکردند. گروههای شرکتکننده در سال ۲۰۲۲ شامل موارد زیر بودند:
- ابزارهای توسعه، مانند AsyncAPI و SpyderIDE
- زبانها و چارچوبهای برنامهنویسی، مانند Julia ، LFortran ، R و p5.js
- پروژههای علمی، مانند CERN-HSF و SymPy
- برنامههای کاربردی کاربر نهایی، مانند Mautic ، Open Food Facts ، Talawa و Ushahidi
- پروژههای سختافزاری و رباتیک، مانند ExpressLRS و Open-RMF
- پروژههای داده، مانند GeomScale ، GeomStats ، OpenMined و Weaviate
- پروژههای ابری و زیرساختی، مانند cert-manager ، NimbleEdge و Cilium
ما هیچ فرادادهای در مورد پروژهها (مانند تاریخ تأسیس، توزیع جغرافیایی مشارکتکنندگان، تعداد مشارکتکنندگان یا اندازه پایگاه کاربر) جمعآوری نکردیم.
ما از پروژهها خواستیم که مشخص کنند از کدام مجوز متنباز استفاده میکنند.
درباره پروژههای مستندسازی
مشکلات مستندسازی
مهمترین مشکلاتی که سازمانها امیدوار بودند با مستندسازی در برنامه ۲۰۲۲ حل کنند عبارتند از:
توجه داشته باشید که سازمانها میتوانند مشکلات اسنادی متعددی را گزارش دهند. برای جزئیات بیشتر، به صفحه نتایج فصل اسناد ۲۰۲۲ مراجعه کنید که به پیشنهادهای اصلی پروژه و مطالعات موردی کامل برای هر سازمان پیوند دارد.
انواع مستندات ایجاد شده
مستندسازی «چگونه میتوان» رایجترین نوع مستندسازی ذکر شده در مطالعات موردی سال ۲۰۲۲ بود.
سایر انواع مستندات ذکر شده در مطالعات موردی عبارتند از:
- شروع سریع
- واژهنامه
- سوالات متداول
- پایگاه دانش
- قطعات
- محتوای وبلاگ/رسانههای اجتماعی
- راهنمای نگهداری
برخی از این دستهها مبهم هستند و یک پروژه مستندسازی میتواند شامل چندین نوع یا ویژگی مستندسازی باشد.
برای جزئیات بیشتر، به صفحه نتایج فصل اسناد ۲۰۲۲ مراجعه کنید، که به طرحهای اولیه پروژه و مطالعات موردی کامل برای هر سازمان پیوند دارد.
بودجهها
میانگین درخواست بودجه ۱۱۶۷۹ دلار و میانه آن ۱۲۱۵۰ دلار بود. پنج سازمان بالاترین کمک هزینه موجود (۱۵ هزار دلار) را درخواست و دریافت کردند و سه سازمان کمترین کمک هزینه (بین ۵ تا ۷ هزار دلار) را درخواست کردند.
معیارها
پروژهها در مطالعات موردی خود، معیارهایی را که برای سنجش موفقیت پروژههای مستندسازی خود استفاده میکردند، تشریح کردند.
معیارهای پیشنهادی برتر عبارت بودند از:
سایر معیارهای پیشنهادی شامل موارد زیر بود:
- درخواستها/کمکهای بیشتر برای مستندات
- بازخورد مستقیم بیشتر در صفحات مستندات
- زمان صرف شده در صفحه
- مسائل مطرحشده (بهعنوان نمونهای برای استفاده)
- شرکتکنندگان در انجمنها
- تعداد شرکا/داوطلبان/ادغامشدگان
- کاهش نرخ پرش
- افزایش آگاهی در جامعه.
به دلیل فاصله کوتاه بین اتمام پروژههای نگارش فنی و ارسال مطالعات موردی، اکثر شرکتکنندگان در سال ۲۰۲۲ نتوانسته بودند در زمان ارسال مطالعات موردی خود، دادههای کافی جمعآوری کنند تا مشخص شود که آیا معیارهای اولیه آنها برآورده شده است یا خیر.
همزمان با دریافت پاسخهای نظرسنجیهای بعدی در سال ۲۰۲۳، این گزارش را بهروزرسانی خواهیم کرد تا اطلاعاتی در مورد اینکه کدام پروژهها به معیارهای خود دست یافتهاند یا معیارهای خود را اصلاح کردهاند، اضافه کنیم.
برای جزئیات بیشتر، به صفحه نتایج فصل اسناد ۲۰۲۲ مراجعه کنید، که به طرحهای اولیه پروژه و مطالعات موردی کامل برای هر سازمان پیوند دارد.
همکاری با نویسندگان فنی
در برنامهی Season of Docs، انتظار میرود پروژهها مستقیماً نویسندگان فنی را جذب، مصاحبه، استخدام و حقوق دهند. نویسندگان فنی میتوانند خود را به فهرستی که توسط Season of Docs در مخزن GitHub ما نگهداری میشود، اضافه کنند، اما کارکنان Season of Docs نویسندگان فنی را بررسی یا توصیه نمیکنند.
بهترین شیوهها برای استخدام نویسندگان فنی برای پروژههای متنباز
از پروژهها خواسته شد تا بهترین شیوههای خود را برای جذب، استخدام و همکاری با نویسندگان فنی به اشتراک بگذارند. توصیههای برتر عبارت بودند از:
استخدام
- با کاندیداهای کمتری مصاحبه کنید و به جای اینکه فقط رزومهها را مرور کنید، از یک جلسه تمرینی زنده استفاده کنید.
- مهارتهای ارتباطی کتبی و شفاهی را بر مهارت در زبان یا ابزار پروژه خود ارجح بدانید
- مستقیماً در مورد چگونگی کسب دانش تخصصی لازم برای کار با پروژه شما توسط نویسنده فنی سوال بپرسید.
- کسی که به ماموریت پروژه شما اشتیاق دارد و ارزشهای اصلی متنباز را به اشتراک میگذارد، احتمال بیشتری دارد که در طول کل پروژه انگیزه خود را حفظ کند.
- پذیرای متقاضیان از سراسر جهان باشید، زیرا تنوع دیدگاهها و پیشینهها به پروژه شما کمک خواهد کرد - اما توجه داشته باشید که داشتن نویسندگان و مربیانی در مناطق زمانی متضاد ممکن است نیاز به تلاش زیادی برای حفظ ارتباط خوب داشته باشد.
استخدام
- از قراردادی استفاده کنید که به وضوح موارد قابل تحویل، برنامههای پرداخت و تعهدات زمانی خاص را شرح دهد.
- اگر پروژه شما ناشناختههای زیادی دارد، جدا از ایجاد مستندات، یک نقطه عطف برای کشف یا تحقیق در نظر بگیرید.
هماهنگی و ارتباطات
- یک گزارش از تصمیمات ثبتشده در جلسات داشته باشید تا درک زمینه و مراحل بعدی برای همه افرادی که روی پروژه کار میکنند، آسانتر شود.
- در مورد نوع ارتباط مورد انتظار و تعداد دفعات آن، چه تماسهای هفتگی، ایمیلهای روزانه یا بهروزرسانی وضعیت در یک کانال چت، شفاف باشید.
- پاسخگو باشید و بازخورد واضحی ارائه دهید که شامل «چرا» باشد و نه فقط «چه»
- نویسندگان فنی خود را با جامعه وسیعتری مرتبط کنید تا به آنها زمینه بدهید و کارشان را اجتماعی کنید.
فرآیندها و ابزارآلات
- یک فرآیند مستندسازی ایجاد کنید که فراتر از برنامه «فصل مستندسازان» ادامه داشته باشد و کل جامعه بتواند در آن مشارکت کند.
- بررسی مستندات حداقل به اندازه بررسی کد طول میکشد و به همان اندازه فشرده است؛ مطمئن شوید که زمان کافی برای آن در نظر میگیرید.
برخی از توصیهها برای وضوح بیشتر ویرایش و خلاصه شدهاند.
همانند برنامه ۲۰۲۱، اکثر نویسندگان فنی در فصل مستندسازی ۲۰۲۲ مستقیماً برای سازمانهایی که با آنها کار میکردند، درخواست دادند.
مشکلات رایج در کار با نویسندگان فنی
پروژههای کمتری در برنامه ۲۰۲۲ مشکلاتی را در همکاری با نویسندگان فنی خود گزارش کردند. بزرگترین مشکل، ناتوانی نویسندگان فنی در تکمیل برنامه به دلیل بیماری، داشتن شغل تمام وقت یا عدم توانایی در انجام تعهد زمانی بود.
یکی از پروژهها گزارش داد که پروژه مستندسازی آنها به کارهایی که به عنوان بخشی از برنامه Google Summer of Code انجام میشد، وابسته بود و مدیریت این وابستگیها دشوار بود. پروژه دیگری زمانی با مشکل مواجه شد که سختافزاری که نویسنده فنی آنها برای مستندسازی نیاز داشت، توسط وزارت دفاع کشور نویسنده مصادره شد و امکان واردات آن وجود نداشت.
نظرسنجیهای بعدی
سه نظرسنجی تکمیلی در ماههای مه، اوت و نوامبر ۲۰۲۳ برای ۲۰۲۲ شرکتکننده ارسال خواهد شد. ما این بخش را با نتایج دریافتی بهروزرسانی خواهیم کرد.
سوالات آینده
مثل همیشه، هر چه بیشتر در مورد مستندات متنباز یاد میگیریم، بیشتر میخواهیم یاد بگیریم!
در فصلهای آینده، امیدواریم:
- برای بررسی همبستگی بین قدمت پروژه، اندازه جامعه یا نیازهای زبانی و مستندسازی، فرادادههای بیشتری از پروژه جمعآوری کنید.
- پروژههای مستندسازی را تجزیه و تحلیل کنید تا ببینید آیا میتوان آنها را به قالبهای قابل اشتراکگذاری تعمیم داد یا خیر.
- تدوین یک دستورالعمل برای مصاحبه با نویسندگان فنی در پروژههای متنباز
اگرچه سوالات زیادی وجود دارد که میخواهیم بررسی کنیم، اما میخواهیم به وقت مدیران و توسعهدهندگان پروژههای متنباز که در فصل مستندات شرکت میکنند نیز احترام بگذاریم. اولویت اصلی این برنامه، حمایت از پروژهها در حل مشکلاتشان با مستندات است.