این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه پروژه
- سازمان منبع باز:
- Matplotlib
- نویسنده فنی:
- جرومف
- نام پروژه:
- توسعه مسیرهای ورودی Matplotlib
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
مقدمه
پیشنهاد پروژه Matplotlib برای فصل Google Docs امسال شامل ایجاد محتوایی است که به معرفی Matplotlib به کاربران جدید کمک می کند. برای توسعه مسیرهای ورودی Matplotlib، من یک رویکرد جایگزین برای اسناد فعلی پیشنهاد می کنم. من یک نویسنده فنی جدید در صنعت هستم. با این حال، سابقه من در آموزش و پرورش و رشته های تحصیلی مجاور است. نوشتار فنی و آموزش شباهت‌های قوی دارند که بر تولید محتوایی متمرکز است که همدلی می‌کند و کاربران را قادر می‌سازد تا وظایف خود را با منابع ارائه شده انجام دهند.
در این زمینه، اسناد Matplotlib با بهبود همدلی با کاربران جدید مفید خواهد بود. بسیاری از مطالب در حال حاضر شامل داده های تصادفی و تصاویر بدون برچسب است. اینها برای نمایش سریع تصاویر و ویژگی های Matplotlib عالی هستند. با این حال، برای استفاده شخصی که تازه وارد Matplotlib شده است، عبور از تبدیل داده ها به تصاویر چالش برانگیز است.
یک زمینه در رویکرد توضیحی راه حلی برای این مانع است. با نوشتن رویه ای از دریچه یک مثال دنیای واقعی، درک محیطی که کاربر در آن کار می کند را نشان می دهیم. این رابطه اسناد و مدارک و کاربر را از نظر رسیدن به یک هدف یا انتظار برای انجام یک کار بهبود می بخشد.
یک کاربر یک هدف مشتق شده ثابت دارد، به عنوان مثال، یک دانشمند داده در یک شرکت کفش باید داده های مشتری را به یک تیم ارائه دهد تا روند خرید را در طول زمان نشان دهد. در این شرایط، کاربر باید یاد بگیرد که در Matplotlib ناوبری کند و از ابزارهای موجود در کتابخانه برای تکمیل کار در دست استفاده کند.
با زمینه اضافی برای پشتیبانی از مستندات، یک کاربر جدید ممکن است بیشتر بتواند موضوع را شناسایی کند. هدف مشتق شده کاربر موازی با مستندات است. من امیدوارم که به سمت چشم‌اندازی کار کنم که تام کاسول، توسعه‌دهنده اصلی، در مصاحبه‌ای در سال 2017 در مورد آن صحبت کرد: «داشتن کسی که واقعاً می‌تواند بنویسد و با کاربران همدلی داشته باشد، کتابی 200 صفحه‌ای «معرفی Matplotlib» بنویسد و اساساً بنویسد. این ورودی اصلی به اسناد باشد."
رویکرد جایگزین نگارش توضیحی
اسناد فعلی ویژگی های Matplotlib را نشان می دهد، یعنی کارهایی که کاربر می تواند با کتابخانه انجام دهد. به عنوان مثال، یک آموزش اغلب از الگوی پیروی می کند که شامل توضیح روش اساسی نیست.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
اغلب با مستندات برنامه نویسی و پشتیبانی، به کاربر توصیه می شود که کد را به تنهایی اجرا کند تا بفهمد چه اتفاقی می افتد. اگرچه طرز فکر برنامه نویسی درک کاربر از موضوع را بهبود می بخشد، منحنی یادگیری برای تحولات محتوای پشتیبانی کمی دارد. از آنجایی که اسناد محدود است، می تواند چالشی بزرگ باشد.
ارائه نمودارها، تصاویر یا سایر تصاویر بصری اضافی به ایجاد فرصت های یادگیری جدید کمک می کند. ساختار زیر نیز به خوبی به عنوان یک الگو برای محتوای جدید عمل می کند. همچنین، نکته اضافه کردن تصاویر یا گرافیک غیر متنی می تواند از ویژگی هایی مانند callouts و coachmarks بهره مند شود. مواقعی وجود دارد که پیمایش تصاویر بدون اشاره به نحوه یا مکان تبدیل کد به خروجی اجرا شده دشوارتر است. من معتقدم که یک عنصر بصری قوی وجود ندارد که می تواند درک بیشتری از موضوعات را تقویت کند.
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
پتانسیل عظیمی در این رویکرد جایگزین استفاده از نوشتن توضیحی برای مستندسازی وجود دارد. با مشاهده انواع مفاهیم برای تبدیل کاربران، آنها می توانند استراتژی های اساسی توسعه تجسم داده ها را بهتر شناسایی کنند. این دانش می تواند به کاربران کمک کند تا نوآوری کنند و از ویژگی های ارائه شده توسط مثال های مبتنی بر موارد استفاده واقعی بهره ببرند.
همانطور که Matplotlib در محبوبیت بیشتر می شود، ثبات در سهولت استفاده و قابلیت دسترسی گواهی بر شهرت کتابخانه است. این ویژگی‌ها خود را به نشان دادن الگوها و استراتژی‌های رایجی می‌رسانند که می‌توانند نه تنها در کد، بلکه در اسناد نیز ظاهر شوند. اگر Matplotlib برای برنامه‌نویسی ساده و استاندارد برای کاربران باشد، همانطور که در استفاده رو به رشد و گسترش منابع آن مشهود است، می‌تواند برای مستندات فنی نیز چنین باشد.
هنگامی که کاربران با مشکلاتی مواجه می شوند، استفاده از جستجو برای حل آنها معمول است. به جای تکیه بر جستجو به عنوان روش اصلی ناوبری، ایجاد برنامه درسی خود در مستندات توسط کاربران می تواند تاثیرگذارتر باشد. از این نظر، کاربر به دنبال راه‌حلی برای مشکل خود می‌گردد، سپس هنگامی که با مشکل دیگری مواجه می‌شود یا اطلاعات بیشتری می‌خواهد، از پیوندهای تعبیه‌شده و کامل در سراسر آن استفاده می‌کند.
این شامل یک معماری از پایین به بالا در سیستم سازمانی است. برای هر موضوع در Matplotlib، یک شبکه غنی از پیوندها به پیوندهای موضوعی و همچنین موضوعات اطلاعاتی به ایجاد یک شبکه قوی کمک می کند. در سراسر این شبکه، کاربر به احتمال زیاد به استفاده از اسناد و مدارک ادامه می دهد تا به موضوع خود پیمایش کند و اطلاعات بیشتر و بیشتر مرتبط با آن موضوع را کشف کند.
موانع
همیشه چالش هایی با پروژه ای به این جامعیت و جزییات وجود دارد. به عنوان یک نویسنده فنی جدیدتر در صنعت، تجربه محدودی در استفاده از Sphinx و ReST برای نوشتن مستندات دارم. من همچنین در مورد Matplotlib و همچنین Git مبتدی هستم. مقابله با این چهار سیستم و راحت شدن با استفاده از آنها برای همکاری و تحقیق زمان می برد. برای ایجاد پایه و اساس لازم برای مسیرهای سطح ورودی، باید زمانی را در طول مرحله پیوند جامعه و قبل از آن به آن اختصاص دهم. در طول این مدت، اگر با مفاهیم و اصول اولیه مشکل داشته باشم، باید برای حمایت بیشتر با جامعه تماس بگیرم.
هماهنگی تلاش‌های مشترک در مناطق زمانی و بر روی پلت‌فرم‌های آنلاین نیز نیاز به تعدیل دارد. راه‌های ارتباطی مختلفی وجود دارد که مردم در سراسر صنعت از آنها استفاده می‌کنند، بنابراین باید مطمئن شویم که در همه رسانه‌ها در دسترس و قابل دسترس هستم. من در اولویت بندی انتظارات مختلف در سراسر جهان شفاف خواهم بود. اگرچه من تازه شروع به کار با چنین کاری در صنعت کرده‌ام، اما روی این سرمایه‌گذاری شده‌ام که خودم را مسئول بدانم و در معرض بازخورد و انتقاد باشم. من احساس می‌کنم که این ویژگی‌ها بدون توجه به رشته ارزشمند هستند.
همچنین، افزایش تست قابلیت استفاده بخشی از مستندات است که به اعتقاد من برای مسیرهای ورودی Matplotlib مفید خواهد بود. انجام نظرسنجی برای کاربردپذیری در مورد محتوا، به منظور ارائه نمایه یک کاربر، یعنی پرسوناها انجام می شود. اطلاعاتی مانند تجربه کاربر، صنعت آنها و سابقه عیب یابی ارزشمند هستند. این قطعات به شکل گیری زبان پشت رویه کمک می کنند. وقتی نوشتن با خوانندگان در سطح خود ملاقات می کند، محتوا فراتر از عمل کردن به عنوان صرفاً آموزشی رشد می کند.
مشکلات بزرگ اغلب با ایجاد یک تمرین مداوم آزمایش قابلیت استفاده است. بسیار معمول است که در طول توسعه محتوا یک نمونه آزمایش انجام شده باشد. تست قابلیت استفاده منظم به پیشبرد روایت محتوا کمک می کند. امیدوارم بتوانم یک برنامه زمان بندی تنظیم کنم یا آزمایش های مکرر قابلیت استفاده را با جامعه Matplotlib انجام دهم.
نتیجه گیری
من تجربه کمی از Python و همچنین Matplotlib در اوقات فراغتم دارم. مقداری که در چند ماه گذشته به خودم یاد دادم با پشتیبانی اسناد فعلی و کنجکاوی خودم بود. تعداد انگشت شماری از ویدئوها و مربیان من در آن زمان نیز وجود داشت. من هنوز چیزهای زیادی برای یادگیری و حتی فضای بیشتری برای پیشرفت دارم زیرا برنامه درسی برنامه نویسی خود را می سازم که به آن علاقه دارم.
پس از دیدن ایده‌هایی که Matplotlib و جامعه برای GSoD دارند، احساس می‌کنم که برای بهبود مهارت‌هایم به‌عنوان یک نویسنده فنی و این فرصت برای یادگیری بیشتر از افراد پشت صحنه، تجربه‌ای رو به رشد عالی خواهد بود. من احساس کرده ام که این پروژه Matplotlib هم معنادار است و هم چیزی که در ایدئولوژی به آن علاقه دارم.
برای کار بر روی بازنگری راهنمای استفاده، هدف من به عنوان یک نویسنده فنی این است که به کاربران کمک کنم تا کارهایی را که می خواهند انجام دهند بدون اینکه تحت تأثیر ویژگی های موجود قرار بگیرند. من معتقدم که بهترین مستندات به رشد و انطباق با کاربران ادامه خواهد داد و به هر کاربری اجازه می‌دهد تا به راه‌حل‌های خود پیمایش کند.