گزارش مطالعه موردی 2021

فاز فعلی:
برنامه Season of Docs 2021 در 14 دسامبر 2021 به پایان رسید. جدول زمانی را ببینید.

توجه: این گزارش داده‌های برنامه‌های اصلی برنامه و مطالعات موردی نهایی سازمان‌ها را خلاصه می‌کند. مطالعات موردی کامل از صفحه نتایج Season of Docs 2021 پیوند داده شده است.

درباره Season of Docs

Season of Docs یک برنامه پایداری است که توسط دفتر برنامه‌های منبع باز Google مدیریت می‌شود. اهداف Season of Docs عبارتند از:

  • ارائه پشتیبانی از پروژه های منبع باز برای حل مشکلات پروژه با مستندات
  • به نویسندگان فنی فرصت هایی برای کسب تجربه در متن باز بدهید
  • آگاهی از متن باز، اسناد و نگارش فنی را افزایش دهید
  • جمع آوری و به اشتراک گذاری اطلاعات در مورد معیارهای موثر در اسناد منبع باز

اطلاعات بیشتر درباره Season of Docs در وب سایت برنامه موجود است.

نمای کلی برنامه 2021

تغییرات برنامه 2021

در سال‌های 2019 و 2020، سازمان‌ها و نویسندگان فنی هر کدام به طور جداگانه برای برنامه Season of Docs درخواست دادند و نویسندگان فنی توسط مدیران برنامه Season of Docs با سازمان‌ها مطابقت داده شدند. سازمان‌ها مربیانی را برای کار با نویسندگان فنی ارائه می‌کردند که بر اساس موقعیت مکانی برای کارشان کمک هزینه دریافت می‌کردند. این برنامه اندازه گیری کرد که آیا نویسندگان فنی، مربیان و مدیران سازمان از مشارکت خود در برنامه راضی هستند یا خیر، اما نتایج مستندات را اندازه گیری نکرد.

در سال 2021، تیم Season of Docs تغییرات قابل توجهی در برنامه ایجاد کرد و تمرکز را به سمت اندازه‌گیری نتایج مستندات تغییر داد و به سازمان‌ها و نویسندگان فنی انعطاف‌پذیری بیشتری داد.

  • سازمان ها با پیشنهادات پروژه، از جمله بودجه و معیارهای پیشنهادی، درخواست دادند
  • نویسندگان فنی دیگر از طریق Google برای تطبیق با سازمان‌ها درخواست نمی‌دهند، بلکه مستقیماً برای سازمان‌های پذیرفته شده اعمال می‌شوند
  • سازمان‌های پذیرفته‌شده کمک‌های بلاعوض را از طریق Open Collective دریافت کردند که از آن برای پرداخت به نویسندگان فنی استفاده می‌کردند
  • غرامت نویسندگان فنی توسط سازمان ها تعیین شد
  • سازمان ها ارزیابی های نهایی و مطالعات موردی را ارائه کردند و به نظرسنجی های بعدی پاسخ دادند

یافته های کلی 2021

سازمان های

  • تغییرات در برنامه 2021 منجر به درخواست سازمان های کمتری شد (در سال 2021 در مقایسه با 2020 شاهد 30٪ کمتر سازمان بودیم) اما مدیران سازمان در سال 2021 کمی بیشتر از مدیران سال 2020 از برنامه راضی بودند (93٪ در مقابل 91٪)

مسائل، مدارک و معیارها

  • بیشتر پروژه ها بر ایجاد مستندات برای کاهش بار نگهدارنده (از طریق کاهش مسائل/سوالات) و/یا افزایش مشارکت پروژه (چه توسط کاربران پروژه یا مشارکت کنندگان) تمرکز داشتند.
    • 50٪ از سازمان های پذیرفته شده محتوای آموزشی یا نحوه انجام را ایجاد کردند.
    • بیش از 50 درصد از سازمان‌های پذیرفته شده، اسناد فعلی خود را فاقد، نامنظم یا قدیمی می‌دانستند.
  • پروژه‌ها عموماً می‌خواستند اثربخشی اسناد خود را از طریق تعامل اندازه‌گیری کنند، به‌ویژه مسائل کمتر مطرح‌شده و بازدیدکنندگان بیشتر از اسناد و مشارکت در پروژه‌ها.
  • از نوامبر 2022، با 25 پروژه از 30 پروژه پاسخ داده شده:
    • 18 پروژه گفتند که معیارهای اولیه خود را برآورده کرده اند
    • 5 پروژه معیارهای تجدید نظر شده را برآورده کردند
    • 2 پروژه گفتند هنوز برای گفتن خیلی زود است

مشارکت در برنامه

  • استخدام، استخدام و پرداخت حقوق نویسندگان فنی سخت ترین بخش برنامه برای مدیران سازمان بود.
  • از نوامبر 2022، 24 سازمان از 30 سازمان پاسخ دادند:
    • 18 سازمان هنوز با نویسندگان فنی Season of Docs خود کار می کردند (چه به عنوان یک مشارکت کننده مستمر یا یک منبع برای پاسخ به سؤالات)
      • 4 سازمان با نویسندگان فنی Season of Docs خود در نقش پولی کار می کردند

نکات برجسته 2021

  • چندین پروژه نشان داد که نویسنده فنی آنها قصد دارد پس از پایان برنامه Season of Docs به کار با پروژه خود ادامه دهد.
  • Metanorma آنقدر از نویسندگان فنی واجد شرایط درخواست کرده بود که آنها بودجه مشابهی را برای استخدام یک نویسنده اضافی برای کار در کنار نویسنده Season of Docs در طول برنامه پیدا کردند.
  • موجا گلوبال دریافت که جامعه بسیار درگیر مستندسازی است و یک کارگروه مستندسازی جدید راه اندازی کرد تا به مشارکت کنندگان بیشتری اجازه دهد در مستندسازی پروژه مشارکت کنند.

داده های خلاصه 2021

در سال 2021، 82 سازمان درخواست دادند و 30 سازمان منبع باز در این برنامه پذیرفته شدند. (برای معیارهای انتخاب به راهنمای ایجاد برنامه خود مراجعه کنید.) فهرست کامل سازمان های شرکت کننده را می توانید در وب سایت Season of Docs بیابید. همه 30 سازمان پذیرفته شده گزارش مطالعه موردی نهایی خود را برای تکمیل مشارکت خود در برنامه 2021 ارسال کردند.

درباره سازمان ها

سازمان‌های شرکت‌کننده در Season of Docs 2021 طیف متنوعی از پروژه‌های منبع باز را نمایندگی کردند. گروه 2021 شامل:

  • پروژه های بزرگ زبان مانند جولیا ، پرل و آر
  • پروژه های آموزش، آب و هوا، فین تک، مراقبت های بهداشتی، خدمات کتابخانه، یادگیری ماشینی، طیف سنجی جرمی، قراردادهای عمومی، و روباتیک
  • پروژه‌های متمرکز بر توسعه‌دهنده، از جمله ابزارهای مهندسی آشوب، فازرها، SDK‌های چت بات، خطوط لوله تجزیه و تحلیل ترکیب نرم‌افزار، ابزارهای نظارت بر عملکرد، و ابزارهای برنامه‌نویسی بصری
  • پروژه های مستندسازی برای ابزارهای مستندسازی، مانند Redocly و Metanorma

پروژه های اکوسیستم پایتون بزرگترین زیرمجموعه بودند. گروه 2021 شامل ArviZ، NumPy، MicroPython، PyMC3، PyTorch-Ignite و SymPy بود.

ما هیچ ابرداده‌ای درباره پروژه‌ها (مانند تاریخ تأسیس، توزیع جغرافیایی مشارکت‌کنندگان، تعداد مشارکت‌کنندگان یا اندازه پایگاه کاربر) جمع‌آوری نکردیم.

ما از پروژه‌ها خواستیم که نشان دهند از کدام مجوز منبع باز استفاده می‌کنند.

A bar graph showing the number of projects using each OSS license: Apache 2.0: ten programs; 3-clause BSD: five programs; MIT: five programs; GPL 2.0: 4 programs; LGPL 2.1: 4 programs; Mozilla Public license 2.0: 3 programs; Artistic, Boost, and 2-clause BSD: one program each

مشکلات مستندسازی که توسط سازمان های 2021 بیان شده است، مشکلات بسیار رایجی هم در پروژه های منبع باز و هم در اسناد فنی به طور کلی است.

مهمترین مشکلاتی که سازمانها امیدوار بودند در برنامه 2021 حل کنند عبارتند از:

A bar graph showing the problems reported by organizations: Documentation is lacking for specific use cases of aspects of a project: 14 projects; Documentation is disorganized: 14 projects; Documentation is outdated: 6 projects; Documentation is not consistent: 3 projects; Documentation needs to be converted to a different tool, platform, or format: 2 projects

توجه داشته باشید که سازمان ها می توانند چندین مشکل اسناد را گزارش کنند. برای جزئیات بیشتر، صفحه نتایج Season of Docs 2021 را ببینید که به مطالعات موردی کامل برای هر سازمان پیوند دارد.

انواع اسناد ایجاد شده

در مطالعات موردی 2021، آموزش‌ها متداول‌ترین نوع مستندسازی بودند.

A bar graph showing the documentation types created: Tutorials: 9 projects; How-tos: 6 projects; Getting Started: 3 projects; Examples: 3 projects; Reference: 3 projects; API Docs, Video, Quickstart, Templates, Landing page: 2 projects each

انواع دیگر اسناد ذکر شده در مطالعات موردی شامل خط لوله اسناد به‌عنوان کد، نمودار، واژه‌نامه، راهنمای سبک، پرسش‌های متداول، بین‌المللی‌سازی، Codelab، مدل محتوا، ماژول‌ها، مستندات مفهومی، پیام‌های خطا، تحقیقات کاربر، Readme، پایگاه دانش بود.

برخی از این دسته بندی ها فازی هستند و یک پروژه مستندسازی واحد می تواند شامل چندین نوع سند یا ویژگی باشد.

چندین پروژه به طور خاص با استفاده از چارچوب Diátaxis به عنوان راهنما برای برنامه ریزی انواع اسناد خود ارجاع داده شده اند.

برای جزئیات بیشتر، صفحه نتایج Season of Docs 2021 را ببینید که به مطالعات موردی کامل برای هر سازمان پیوند دارد.

بودجه ها

در سال 2021، متوسط ​​درخواست بودجه 10200 دلار و متوسط ​​​​10000 دلار بود. تنها سه سازمان حداکثر کمک مالی ممکن (15 هزار دلار) را درخواست کردند و دریافت کردند و سه سازمان دیگر کمترین کمک مالی ممکن (5 هزار دلار) را درخواست کردند.

معیارها

پروژه‌ها در مطالعات موردی خود معیارهایی را که برای سنجش موفقیت پروژه‌های مستندسازی خود استفاده می‌کردند، مشخص کردند.

معیارهای پیشنهادی برتر عبارت بودند از:

A bar graph showing documentation success metrics: Fewer project issues/questions: 13 projects; More visitors to documentation/docs usage: 9 projects; More contributors/pull requests: 8 projects; More documentation pull requests/contributions: 7 projects; Total number of docs created: 5 projects; Increased documentation satisfaction (via survey), Increased project use, More direct feedback on documentation pages: four projects each; Better SEO: three projects; Total percentation of documentation converted and Total percentage of target info covered by docs: two projects each

سایر معیارهای پیشنهادی شامل ستاره‌های GitHub، زمان صرف شده در صفحه، تبدیل‌های فهرست پستی، آزمایش کیفی کاربر، تعداد شرکت‌کنندگان در انجمن‌ها، تعداد شرکا/داوطلبان/ادغام‌ها بود .

به دلیل فاصله کوتاه بین تکمیل پروژه‌های نگارش فنی و ارائه مطالعات موردی، اکثر گروه‌های 2021 قادر به جمع‌آوری داده‌های کافی برای تعیین اینکه آیا معیارهای اولیه آنها برآورده شده است یا خیر، نبودند.

برای جزئیات بیشتر، صفحه نتایج Season of Docs 2021 را ببینید که به مطالعات موردی کامل برای هر سازمان پیوند دارد.

کار با نویسندگان فنی

بزرگترین تغییر در برنامه Season of Docs در سال 2021 مربوط به نحوه کار پروژه ها با نویسندگان فنی بود. در فصل‌های قبل، نویسندگان فنی مستقیماً به Google درخواست می‌دادند و توسط مدیران برنامه با پروژه‌ها مطابقت داده می‌شدند و مستقیماً از Google به آنها کمک هزینه پرداخت می‌شد.

در سال 2021، نویسندگان فنی مستقیماً برای پروژه‌ها درخواست دادند و پروژه‌ها با پرداخت‌هایی که از طریق صندوق جمعی باز Season of Docs انجام می‌شد، بودجه را برای غرامت نویسنده فنی تعیین کردند.

اکثر پروژه‌های شرکت‌کننده در برنامه 2021 تجربه کمی در استخدام یا استخدام نویسندگان فنی داشتند و بسیاری از پروژه‌ها این بخش از فرآیند را به‌عنوان بخشی که نیاز به حمایت بیشتری دارد نامیدند. در پاسخ به این بازخورد، تیم Season of Docs اسنادی را برای ایجاد توافقنامه های نویسنده فنی به راهنمای برنامه اضافه کرد.

توصیه های استخدام

از پروژه‌ها خواسته شد تا برای سایر پروژه‌های علاقه‌مند به شرکت در Season of Docs توصیه‌هایی ارائه کنند. توصیه های برتر استخدام عبارت بودند از:

  • مطالب استخدامی برای نویسندگان فنی را هر چه زودتر به اشتراک بگذارید، حتی قبل از اینکه در برنامه پذیرفته شوید. از جامعه خود بخواهید نامزدهای احتمالی را معرفی کند.
  • به طور گسترده در خارج از کانال های پروژه به اشتراک بگذارید. از زبان فراگیر استفاده کنید و مستقیماً نامزدهایی را که دارای پیشینه‌های کم نمایندگی هستند تشویق کنید که درخواست دهند.
  • بدانید چه ابزارهایی برای فرآیند ایجاد اسناد شما ضروری هستند و نویسندگان فنی با تجربه استفاده از آن ابزارها را استخدام کنید.
  • انتظارات روشنی را برای نویسنده فنی در مورد موارد قابل تحویل و نقاط عطف، کانال های ارتباطی و ورود، و فرآیندهای پرداخت و زمان بندی ایجاد کنید.
  • سرمایه گذاری روی اعضای انجمن و کمک به رشد آنها به عنوان نویسندگان فنی با استفاده از نویسنده فنی Season of Docs برای ارائه راهنمایی و مربیگری را در نظر بگیرید.
  • برای حضور در نویسندگان فنی و پاسخگویی به سوالات و ارائه پشتیبانی در طول برنامه زمان بیشتری نسبت به آنچه انتظار دارید اختصاص دهید، به خصوص اگر نویسنده فنی تجربه قبلی در حوزه پروژه شما نداشته باشد.
  • فرآیند استخدام، استخدام و عضویت خود را برای استفاده در پروژه های آینده مستند کنید.

A bar graph showing the source of technical writer candidates: Applied directly to program: 7; SoD GitHub or previous SoD participant: 4; Write the Docs Slack or Community member: 3 each; Applied via jobs site (Upwork, LinkedIn) or Google Summer of Code or Code-In alumni: 2 each

(توجه: همه پروژه‌ها در مطالعات موردی خود که در آن نامزدهای نویسنده فنی خود را استخدام کرده‌اند مشخص نشده‌اند.)

مسائل رایج در کار با نویسندگان فنی

A bar graph showing technical writer issues: TW dropping out: 8 projects; Communications issues: 6 projects; TW onboarding: 4 projects; TW recruitment; Hiring or payment; Project tooling setup: 3 projects each

نویسندگان فنی در چندین پروژه مجبور شدند به دلیل کووید یا سایر بیماری‌ها یا به دلیل مسئولیت‌های خانوادگی مرتبط با بیماری همه‌گیر، ترک تحصیل کنند. برخی از پروژه ها مشکلات ارتباطی مربوط به عدم تطابق منطقه زمانی یا مشکلات اتصال به اینترنت را گزارش کردند.

پروژه‌ها دریافتند که آنها مشکلات مربوط به ورود به انجمن‌های خود یا راه‌اندازی زنجیره ابزار اسناد پروژه خود را دست‌کم گرفتند.

برخی از پروژه‌ها به دلیل مشکلات بانکی با Open Collective یا به دلیل محدودیت‌های پرداختی در کشورهای مبدأ نویسندگان، در پرداخت به نویسندگان فنی خود تاخیر داشتند.

مستندات برنامه در مورد کارمزدهای Open Collective مشخص نبود: Google کارمزد تراکنش‌های Open Collective را برای انتقال اولیه وجوه به پروژه‌ها پوشش می‌دهد، اما هزینه‌های تراکنش‌های اعمال شده توسط برخی کانال‌های پرداخت دیگر (مانند هزینه‌های تبدیل ارز) را پوشش نمی‌دهد. ما تلاش خواهیم کرد تا این موضوع را در مستندات برنامه‌های آینده واضح‌تر کنیم.

بررسی های پیگیری

به عنوان بخشی از برنامه Season of Docs، از پروژه ها خواسته شد تا در نظرسنجی های بعدی شرکت کنند. سه نظرسنجی در ماه مه، آگوست و نوامبر 2022 ارسال شد.

A bar graph showing the number responses to the followup survey: May survey: 13 responses; August survey: 21 responses; November survey: 12 responses

نظرسنجی پیگیری از پروژه‌ها خواسته شد تا تأیید کنند که پیوندهای پیشنهادی و مطالعه موردی آنها هنوز فعال است. این نظرسنجی همچنین شامل سوالاتی در مورد موفقیت پروژه‌های آنها (که با معیارهایی که در مطالعه موردی خود تعیین می‌کنند) و مشارکت و غرامت مستمر نویسندگان فنی پروژه بود:

  1. آیا هنوز با نویسنده فنی Season of Docs خود کار می کنید؟

A bar graph showing ongoing participation by technical writers, per survey: in May, 6 projects had technical writers either participating or answering questions; 1 project had no ongoing technical writer involvement. In August, 11 projects had ongoing technical writer participation; seven projects had no ongoing technical writer participation, and 3 projects had technical writers answering questions. In November, 5 projects reported ongoing technical writer involvement; 3 projects reported no ongoing technical writer involvement; and 4 projects reported technical writers answering questions.

  1. اگر نویسنده فنی شما هنوز با پروژه شما کار می کند، آیا به هیچ وجه جبران می شود؟

A bar graph showing the number of projects reporting their project compensation for technical writers in each survey. In May, 5 projects reported their technical writers were being paid for ongoing work; 4 projects reported their technical writer was unpaid. In August, 4 projects reported paying their technical writer and 7 projects reported their technical writer was unpaid. In November, two projects reported paying their technical writer, and 5 projects reported their technical writer was unpaid.

  1. در این مرحله، آیا فکر می کنید پروژه مستندسازی شما موفق است؟

A bar graph showing the number of projects reporting success against metrics in each survey. In May, 6 projects reported their metrics had been met; 6 projects said it was too soon to tell, and 2 projects had met adjusted metrics. In August, 16 projects reported that metrics had been met; 3 projects reported adjusted metrics had been met; and 2 projects reported it was too soon to tell. In November, 9 projects reported metrics had been met; 3 projects reported adjusted metrics had been met, and no projects reported that it was still too soon to tell.

سوالات آینده

مثل همیشه، هر چه بیشتر در مورد مستندات در متن باز یاد بگیریم، بیشتر می خواهیم بیاموزیم! در فصل های آینده امیدواریم یاد بگیریم:

  • آیا دامنه های پروژه با انتخاب نوع doctype یا انتخاب متریک همبستگی دارند
  • کدام شیوه‌های استخدام و راه‌اندازی نویسنده فنی برای تکمیل پروژه و حفظ نویسنده فنی مؤثرتر است
  • جدول زمانی معقول برای اندازه گیری اثربخشی اسناد

اگرچه سؤالات زیادی وجود دارد که مایلیم بررسی کنیم، اما همچنین می‌خواهیم به زمان مدیران و نگهبانان پروژه منبع باز که در Season of Docs شرکت می‌کنند احترام بگذاریم. اولویت اصلی برنامه حمایت از پروژه ها در حل مشکلات آنها با مستندسازی است.