این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه پروژه
- سازمان منبع باز:
- بوکه
- نویسنده فنی:
- vis_verborum
- نام پروژه:
- ایجاد، خواندن، به اشتراک گذاری: بهینه سازی اسناد بوکه
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
ایجاد، خواندن، به اشتراک گذاری: بهینه سازی اسناد بوکه
1. چکیده
بوکه یک ابزار بسیار قدرتمند برای ایجاد تصاویر تعاملی مبتنی بر مرورگر با پایتون است. پایگاه کاربر قابل توجهی دارد (۵۰۲ هزار بار دانلود ماهانه، ۸۵۵ هزار دانلود PyPi) و تعداد زیادی مشارکت کننده (۴۵۵ مشارکت کننده در GitHub). جای تعجب نیست که اسناد گسترده بوکه به صورت ارگانیک رشد کرده است. و بنابراین، در مکانها، ناسازگار، دشوار برای دسترسی، و پیچیده است.
فصل اسناد Google فرصتی منحصر به فرد برای بررسی و بازنگری متمرکز ساختار و محتوای اسناد بوکه - و اطمینان از اینکه اسناد و ابزارها و گردشهای کاری مرتبط در آینده اثبات میشوند، فراهم میکند.
من پروژههای منبع باز را با Python و Sphinx کدنویسی و مستند کردهام (اخیراً: PyZillow و PyPresseportal ). اما چیزی که من را به یک شرکت کننده منحصربهفرد در فصل اسناد Google تبدیل میکند، سابقه من در روزنامهنگاری است: بیش از 13 سال در اتاقهای خبر کار کردم و سالها به عنوان سردبیر و مدافع تغییرات دیجیتال بودم. علاوه بر وظایف روزنامه نگاری، مسئولیت های فزاینده ای در طراحی و مستندسازی ابزارهای دیجیتال جدید و راهنمای سبک و همچنین آموزش کارکنان اتاق خبر داشتم.
پس از مهاجرت اخیر از اروپا به ایالات متحده، تصمیم گرفتم راه های جدیدی را برای گرد هم آوردن اشتیاق خود برای ارتباط و کدنویسی جستجو کنم. من نوشتم فنی را ترکیبی بهینه از مهارت ها و تجربیات من در زمینه نویسندگی و فناوری یافتم. در این پیشنهاد، نحوه استفاده از فصل اسناد Google را برای بهینهسازی مستندات بوکه بیان میکنم: با ایجاد راحتتر و مشارکت در اسناد، با سادهتر کردن خواندن اسناد و با سهولت اشتراکگذاری اطلاعات در اسناد با دیگران.
2. وضعیت فعلی
اسناد رسمی بوکه شامل این واحدهای اصلی است:
- مستندات روایت: راهنمای نصب، راهنمای کاربر، راهنمای توسعه دهندگان، یادداشتهای انتشار
- گالری و دموها (نمونه های تعاملی با کد منبع آنها)
- راهنمای مرجع (اسناد بر اساس رشتههای اسنادی)
- آموزش (مجموعه گسترده ای از نوت بوک های Jupyter، میزبانی شده در mybinder.org)
- Docstrings و مدل کمک برای IDE ها
- نمونه ها و README ها در مخزن پروژه
علاوه بر این، اطلاعات زیادی در انجمن پشتیبانی Bokeh و Stack Overflow وجود دارد، جایی که توسعهدهنده Bokeh فعالانه به سؤالات کاربران پاسخ میدهد، و همچنین در وبلاگ Bokeh's Medium.
اکثر صفحات وب مستندات با Sphinx ایجاد می شوند و از چندین پسوند استاندارد و سفارشی Sphinx استفاده می کنند. برای مثال، راهنمای مرجع، از رشتههای اسناد، با استفاده از پسوندهایی مانند «autodoc» و سفارشی «bokeh_autodoc» تولید میشود. همانطور که ماهیت اسناد رشد یافته ارگانیک است، حاوی موارد اضافی و ناسازگاری است.
یکی از اولین چیزهایی که هنگام تجزیه و تحلیل اسناد موجود متوجه شدم، فقدان دستورالعمل های سبک روشن برای نوشتن مستندات بود. راهنمای توسعهدهنده بوکه حاوی دستورالعملهای اساسی است. با این حال، این سند حاوی راهنمایی های زیادی در مورد سبک نیست، به ویژه در مورد اسنادی که فراتر از رشته های مستند است. در نتیجه، مسائل سبکی و ساختاری دسترسی به اطلاعات موجود در اسناد را به ویژه برای افراد تازه وارد دشوارتر می کند.
به عنوان مثال:
- استفاده از اسامی، حروف و کلمات غیر معمول به جای افعال واضح و قوی، برخی از متن را بی دلیل پیچیده می کند: "مشاهده اصلی این است که استفاده معمولی شامل ایجاد اشیاء طرح با تابع figure() است." این باید برای سهولت خواندن بازنویسی شود. به عنوان مثال: "تابع figure() رایج ترین تابعی است که برای ایجاد اشیاء نمودار استفاده می شود."
- برخی جملات بسیار طولانی هستند و درک آنها را دشوار میکند: «بعد میتوانیم vbar را با فهرست فاکتورهای نام میوه بهعنوان مختصات x، ارتفاع میله را بهعنوان مختصات بالا، و در صورت تمایل هر عرض یا ویژگیهای دیگری را که میخواهیم نام ببریم. مجموعه» . جملات طولانی تر باید به جملات کوتاه تر یا لیست های گلوله ای تقسیم شوند. جملات ساده به ویژه برای کاربران مبتلا به نارساخوانی یا افرادی که از انگلیسی به عنوان زبان اول خود استفاده نمی کنند مفید خواهد بود (به شماره 10160 مراجعه کنید).
- استفاده متناقض از «شما» و «ما» که گیجکننده و حواسپرتکننده است: «دو روش اساسی وجود دارد که میتوان بسته به مورد استفاده شما استفاده کرد» و «ما میتوانیم تمام سریهای سال را با استفاده از تماسهای جداگانه ترسیم کنیم» (دو مثال). از همان صفحه ). برخی از صفحات حتی به روشهای متفاوتی به خوانندگان خطاب میکنند، مانند: «کاربران ممکن است مجبور باشند وابستگیهای بیشتری نصب کنند» یا «کسی میتواند طرحبندیهای پیچیدهتری ایجاد کند» .
- اشتباهات تایپی، کلمات گم شده و اضافی، و اشتباهات گرامری جریان خواندن را از بین می برد و به اعتبار اطلاعات آسیب می رساند: "بوکه ایجاد نمودارهای میله ای اولیه را ساده می کند" یا "به بخش حروف نگاره ها در راهنمای کاربر مراجعه کنید" .
- ناهماهنگیهای ساختاری میتواند برای خوانندگان ناامیدکننده باشد: مانند داشتن مثالهایی با حاشیهنویسی خوب در یک صفحه و عدم توضیح مثالها در صفحه دیگر .
صفحه فرود مستندات بوکه نسبتاً کوتاه است و شامل اطلاعاتی در مورد همه منابع موجود نمیشود (هیچ اشارهای به کتابخانه گسترده رشتههای اسناد و توابع کمک مدل، انجمنهای پشتیبانی، دموها یا وبلاگ متوسط نمیشود). این همچنین شروع کار با بوکه را برای کاربران جدید دشوارتر می کند.
3. اهداف
برای استفاده موثرتر از مرحله توسعه سند یازده هفته ای، بر سه عنصر کلیدی تمرکز خواهم کرد:
3.1. ایجاد اسناد را بهبود بخشید
بیشتر اسناد Bokeh توسط مشارکتکنندگانی نوشته شده است که اسناد را به عنوان بخشی از درخواستهای کششی برای قابلیتهای جدید و رفع اشکالها شامل میشوند. در حالی که من از برخی از مراحل توسعه سند برای ویرایش و اصلاح اسناد موجود استفاده خواهم کرد، اما بر ایجاد گردش کار برای ایجاد و نگهداری اسناد برای اثبات آینده تاکید می کنم: باید تا حد امکان برای مشارکت کنندگان آسان باشد که استانداردهای بالایی از اسناد را حفظ کنند. .
من این را با دو رویکرد تضمین خواهم کرد:
- من مجموعه ای از دستورالعمل های سبک کاربردی و ساده ایجاد خواهم کرد تا در راهنمای توسعه دهندگان موجود گنجانده شود. این دستورالعمل ها به سبک، دستور زبان و ساختار می پردازد. علاوه بر این، من از کانال های ارتباطی داخلی مانند Slack استفاده خواهم کرد تا مطمئن شوم که مشارکت کنندگان بوکه از دستورالعمل های سبک آگاه هستند. من همچنین جلسات تمرین و پرسش و پاسخ را برای تیم ارائه خواهم داد.
- من با تیم اصلی کار خواهم کرد تا مجموعه ای از ابزارهای بهینه را برای کنترل کیفیت اسناد پیدا کنم که به گردش کار موجود بوکه برای PR (درخواست های کشش) و CI (ادغام مداوم) اضافه می شود. بسته به نیازهای تیم، این میتواند به معنای افزودن ابزارهایی مانند pydocstyle ، proselint ، یا sphinxcontrib-spelling spelling به مجموعه آزمایشی Bokeh، تنظیمات پیشفرض یا اقدامات GitHub باشد. من یک اثبات کار مفهوم را به اقدامات GitHub یکی از پروژه های منبع باز خود اضافه کرده ام.
3.2. خواندن اسناد را بهبود بخشید
هدف از مستندسازی خوب این است که کاربران فعلی و آینده نگر را به راحتی پیدا کنند و اطلاعات درست را پیدا کنند و بتوانند تا حد امکان از این اطلاعات استفاده کنند.
عوامل کلیدی برای کاربردپذیری یک متن، سبک و ساختار آن است: نوشتن مستندات به شیوه ای واضح و ثابت به خوانندگان اجازه می دهد تا اطلاعات را به سرعت، بدون حواس پرتی و زبان اضافی دریافت کنند. ساختار ساده و شفاف اسناد، یافتن سریع اطلاعات مرتبط را آسان می کند.
من با تأکید بر قابلیت استفاده برای کاربران جدید، بر روی هر دو حوزه تمرکز خواهم کرد. این شامل بررسی کامل مستندات روایت، با محوریت راهنمای کاربر است. من همچنین صفحه فرود اسناد را بازنگری خواهم کرد تا با وضوح بیشتری به مخاطبان هدف مختلف بپردازم و مطمئن شوم که هر کاربر می تواند منابع مناسب را به سرعت پیدا کند.
درست مانند بهبود ایجاد اسنادی که در بالا ذکر شد، من بر ایجاد پایه ای برای پیشرفت های آینده و استانداردهای بالا برای مستندات بوکه تمرکز خواهم کرد.
3.3. بهبود اشتراک گذاری اسناد
بحث بیشتر و بیشتر در مورد بوکه در سیستم عامل های شخص ثالث اتفاق می افتد. بسیاری از این پلتفرم ها از ابرداده مانند OpenGraph فیس بوک برای گنجاندن پیش نمایش های غنی از پیوندها استفاده می کنند. OpenGraph توسط سرویس هایی مانند Facebook، Twitter، LinkedIn، Slack و iMessage استفاده می شود. انجمن گفتمان بوکه همچنین از OpenGraph برای ارائه پیش نمایش پیوندها استفاده می کند.
برای استفاده از این فناوری، همانطور که در شماره 9792 توضیح داده شد، فراداده را به صفحات وب ایجاد شده توسط بوکه بوکه اضافه خواهم کرد. کارآمدترین راه استفاده از پسوند اختصاصی Sphinx است. چند روز پیش، اولین نسخه از یک افزونه Sphinx برای داده های OpenGraph در GitHub منتشر شد. من از برخی از مراحل توسعه اسناد برای کمک به بهبود این پسوند برای استفاده در اسناد بوکه استفاده خواهم کرد.
من همچنین اثبات مفهومی را ایجاد کرده ام که با موفقیت در یکی از پروژه های منبع باز خود، PyPresseportal استفاده می کنم. این برنامه افزودنی به طور خودکار اطلاعات مرتبط مانند عنوان، توضیحات، تصویر و URL را جمع آوری می کند. سپس این اطلاعات را به عنوان تگ OpenGraph در کد HTML تولید شده توسط Sphinx قرار می دهد.
گام بعدی در توسعه این افزونه، معرفی دستورالعملهای سفارشی برای تعریف دستی ابرداده OpenGraph (مشابه دستورالعملهای متا موجود در docutil) است. ابردادههای تولید شده بهطور خودکار تنها بهعنوان بازگشتی استفاده میشوند، در صورتی که دادهای وارد شده بهصورت دستی در دسترس نباشد.
پشتیبانی از دادههای ساختاریافته بسیار پیچیدهتر است، بنابراین من در درجه اول بر روی اضافه کردن ابرداده OpenGraph با کیفیت بالا برای اسناد بوکه تمرکز خواهم کرد. تمام کارهایی که برای پشتیبانی از OpenGraph انجام می شود، در همان زمان، پایه های پشتیبانی از داده های ساختاریافته را ایجاد می کند.
اعضای انجمن Sphinx و ReadTheDocs برای توسعه برنامههای افزودنی برای OpenGraph و Structured Data ابراز علاقه کردهاند (مثلاً در شمارههای #1758 و #5208 )، و من مطمئن خواهم شد که از نزدیک با آنها کار خواهم کرد.
4. قابل تحویل
به طور خلاصه، اینها موارد قابل تحویلی هستند که انتظار دارم از Season of Docs خارج شوند:
- دستورالعملهای سبک مستندسازی برای مشارکتکنندگان بوکه
- گردشهای کاری PR و CI برای شامل کنترل کیفیت اسناد خودکار
- راهنمای کاربر ویرایش و بازسازی شده
- صفحه فرود اسناد اصلاح شده
- فراداده OpenGraph موجود در صفحات وب مستندات و یک برنامه افزودنی Sphinx در حال کار است
علاوه بر این، من یک "doclog" برای مستند کردن سفر خود در فصل Google's Docs در وب سایت شخصی/Medium یا وبلاگ Bokeh's Medium نگه خواهم داشت. این همچنین به عنوان مبنایی برای گزارش پروژه برای Google عمل می کند. من همه کارها را به صورت شفاف، در قالب مشکلات GitHub و درخواست کشش، در صورت امکان انجام خواهم داد.
5. جدول زمانی
قبل از مرحله پیوند با جامعه: من قبلاً به طور فعال در چندین بحث در مورد مخزن GitHub Bokeh شرکت می کنم و با برایان ون دی ون و پاویترا اسوارامورتی، مربیان بوکه برای فصل اسناد Google در تماس بوده ام. من در گفتگو در مورد بوکه فعال می مانم و همچنین با ساخت و انتشار تصاویر بصری با بوکه بیشتر آشنا خواهم شد.
مرحله پیوند جامعه (08/17 - 09/13):
- تیم اصلی را بشناسید، طرح پروژه را در ازای با مربیان اصلاح کنید
- یک برنامه و کانال های ارتباطی برای گزارش منظم و بازخورد با مربیان تنظیم کنید
- در Bokeh's Slack فعال باشید تا به همه مشارکت کنندگان علاقه مند Bokeh در مورد فصل Google Docs و اهداف مرحله توسعه doc اطلاع دهید.
- جمع آوری بازخورد از مشارکت کنندگان بوکه برای اصلاح بیشتر طرح برای مرحله توسعه سند
مرحله توسعه Doc
هفته 1، 09/14 - 09/20:
- ممیزی و ویرایش اسناد روایی را شروع کنید
- شروع به تهیه پیش نویس دستورالعمل های سبک
هفته 2، 09/21 - 09/27:
- به کار بر روی دستورالعمل های سبک ادامه دهید
- به ویرایش اسناد روایی ادامه دهید
- بازبینی کلی صفحه فرود اسناد را شروع کنید
هفته 3، 09/28 - 10/04:
- دستورالعمل های سبک را نهایی کنید
- صفحه فرود اسناد را نهایی کنید
هفته 4، 10/05 - 10/11:
- ویرایش نهایی اسناد روایی
- با تیم اصلی بوکه در مورد ادغام ابزارهای کنترل کیفیت اسناد در گردش کار PR/CI بحث کنید.
هفته 5، 10/12 - 10/18:
- برای بحث در مورد دستورالعملهای سبک، بهبود مستندات روایت، و گردشهای کاری PR/CI، جلسه پرسش و پاسخ را با مشارکتکنندگان Bokeh در Slack راهاندازی کنید.
- شروع به توسعه اثبات مفهومی موجود من برای ابرداده OpenGraph در یک پسوند Sphinx قابل استقرار
- دستورالعملهای سبک را بر اساس بازخورد جلسه پرسش و پاسخ با مشارکتکنندگان بوکه اصلاح کنید
هفته 6، 10/19 - 10/25:
- شروع آزمایش ابزارهای کنترل کیفیت اسناد در گردش کار PR و CI
- به توسعه پسوند Sphinx برای ابرداده ادامه دهید
هفته 7، 10/26 - 11/01:
- آزمایش پسوند Sphinx
- دومین جلسه پرسش و پاسخ با مشارکت کنندگان بوکه در Slack
- موارد تحویلی را بر اساس بازخورد جلسه دوم پرسش و پاسخ بازبینی کنید
هفته 8، 11/02 - 11/08:
- برنامه افزودنی Sphinx را گسترش دهید و اسناد روایی بهبود یافته و صفحه فرود اسناد را منتشر کنید
هفته 9، 11/09 - 11/15:
- ابزارهای کنترل کیفیت اسناد را در جریان های کاری PR و CI مستقر کنید
- راهنمای برنامهنویسان را بهروزرسانی و منتشر کنید تا شامل دستورالعملهای سبک و اضافهشدههای گردش کار روابط عمومی و CI باشد
هفته 10، 11/16 - 11/22:
- کارهای باقی مانده را نهایی کنید
هفته 11، 11/23 - 11/29:
- نوشتن گزارش پروژه را شروع کنید
- نوشتن ارزیابی پروژه را آغاز کنید
مرحله نهایی شدن پروژه
هفته 12، 11/30 - 12/05:
- نهایی کردن و ارائه گزارش پروژه
هفته 13، 12/03 - 12/10:
- نهایی کردن و ارائه ارزیابی پروژه
پس از پایان فصل اسناد گوگل:
- من امیدوارم که در توسعه بوکه مشارکت داشته باشم و به کار بر روی مستندات بوکه ادامه دهم.
- من قصد دارم توسعه یک پسوند Sphinx را برای ابرداده OpenGraph/Structured Data ادامه دهم.
- امیدوارم از پیشینه خود در روزنامه نگاری و شبکه موجودم برای تبلیغ بوکه به عنوان ابزاری در روزنامه نگاری داده استفاده کنم. به عنوان مثال، با نوشتن درباره بوکه با در نظر گرفتن مخاطبان روزنامه نگار یا با ارائه سخنرانی در کنفرانس درباره استفاده از بوکه در محیط های روزنامه نگاری.
6. درباره خودم
من در اصل یک روزنامه نگار هستم و سابقه فعالیت در اخبار تلویزیون، آنلاین و رادیو را دارم. کار به عنوان سردبیر و گزارشگر در تلویزیون و اخبار دیجیتال، سالها تجربه در زمینه نویسندگی و تدوین را به من داده است. در همان زمان، من روی چندین پروژه برای ترویج تحول دیجیتال و اتوماسیون کار کردم. من کتابچههای راهنمای متعددی نوشتم که ابزارها و جریانهای کاری دیجیتال را پوشش میداد، و همچنین راهنماهای سبک و استراتژیهای ارتباطی برای برندهای خبری دیجیتال را پوشش میداد. من همچنین اعضای تیم را در استفاده از این ابزارها آموزش دادم.
من همیشه به تقاطع بین ارتباطات و فناوری کشیده شده ام. زمانی که کدنویسی در پایتون را یاد گرفتم، دنیای جدیدی به روی من گشوده شد: به عنوان مثال، توانسته ام برای روزنامه نگاری داده، تحلیل و تجسم داده انجام دهم. همچنین یادگیری کدنویسی به من این امکان را داد که به طور فعال با مهندسان نرم افزار برای توسعه ابزارهای دیجیتال برای گردش کار اتاق خبر همکاری کنم.
راهنماها و اسنادی که در محل کار قبلی ام نوشتم متأسفانه غیر عمومی هستند. بنابراین، من اکنون بر روی مشارکت بیشتر با پروژه های منبع باز تمرکز می کنم (برای مثال به زیر مراجعه کنید). من کار خود را در زمینه نگارش فنی بر اساس راهنماهای سبکی مانند راهنمای سبک مستندسازی توسعه دهندگان گوگل و راهنمای سبک مایکروسافت قرار داده ام. من به طور مرتب از GitHub، Slack و Linux استفاده می کنم. من با استفاده از ابزارهایی مانند Sphinx، Mypy، و Sphinx autodoc، اسناد روایی و همچنین رشتههای مستند و نکات تایپ مینویسم.
در حال حاضر به صورت آزاد کار می کنم. برنامه من انعطاف لازم را برای کار بر روی مستندات بوکه برای حدود 25 ساعت در هفته در طول مرحله توسعه سند فراهم می کند. من در منطقه زمانی اقیانوس آرام کار می کنم اما خوشحالم که برنامه ها و نیازهای تیم را برآورده می کنم.
7. نمونه های اسناد منبع باز اخیر
PyZillow : PyZillow یک پوشش پایتون برای API وب سایت املاک Zillow.com است. من علاوه بر ارائه مقداری کد و ایفای نقش به عنوان یکی از نگهبانان کد، مستندات کامل را نوشتم. من از Sphinx برای مستندات روایت و همچنین برای مرجع ماژول استفاده کردم. من مرجع ماژول را با autodoc پسوند Sphinx بر اساس رشتههای اسنادی که به کد اضافه کردم ایجاد کردم.
PyPresseportal : PyPresseportal یک پوشش پایتون برای API وب سایت presseportal.de است. وب سایت presseportal.de یکی از بزرگترین توزیع کنندگان بیانیه های مطبوعاتی و اطلاعیه های روابط سرمایه گذار در آلمان است. به عنوان مثال، تقریباً تمامی ادارات پلیس و آتش نشانی از این سرویس برای توزیع بیانیه های مطبوعاتی خود استفاده می کنند. پس از سالها استفاده از API به عنوان یک روزنامهنگار، تصمیم گرفتم یک رابط Python برای دسترسی به منابع داده گسترده وب سایت به عنوان اشیاء پایتون توسعه دهم. من کد و کل مستندات مبتنی بر Sphinx را نوشتم.