پروژه Creative Commons

این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.

خلاصه پروژه

سازمان منبع باز:
Creative Commons
نویسنده فنی:
نیمیشنب
نام پروژه:
راهنمای استفاده از واژگان
طول پروژه:
طول استاندارد (3 ماه)

شرح پروژه

خلاصه پروژه

واژگان پتانسیل بسیار زیادی برای استفاده به عنوان یک کتابخانه مؤلفه UI اولیه برای ساخت وب سایت دارد. چیزی که به آن نیاز دارد، یک راهنمای قوی و در عین حال غیرعادی است. اطلاعات مهم توسعه دهنده مانند راهنماهای مؤلفه، مشخصات استفاده و ترفندهای پیکربندی بخش اساسی هر مستندی را تشکیل می دهند. این نه تنها کاربران موجود را تشویق می‌کند تا احساس کنند که چگونه واژگان به رشد خود ادامه می‌دهند و به نقاط عطف جدید می‌رسند، بلکه استفاده از واژگان را در پروژه‌های نسبتاً جدیدتر ترویج می‌کنند. نتایج مطلوب دوره من به عنوان یک کارآموز نه تنها شامل نوشتن یک راهنمای بیهوده برای استفاده از مؤلفه های از قبل موجود است، بلکه همچنین طراحی و توسعه یک صفحه اصلی (که منجر به اسناد یکپارچه برای هر یک می شود) برای Vocabulary، Vue- است. واژگان و فونت ها

طرح پروژه

  1. مشکل: مستندسازی یکی از دلایل اصلی است که تعیین می‌کند یک کتابخانه منبع باز خاص چقدر موفق خواهد بود. سوال اصلی که توسعه دهندگان هنگام انتخاب یک پشته فناوری مناسب برای ساخت برنامه های خود به آن فکر می کنند این است که "آیا کتابخانه به خوبی مستند شده است؟ آیا به خوبی نگهداری می شود؟ آیا استفاده و پشتیبانی قابل توجهی از خطا دارد؟». این دقیقاً همان سؤالاتی است که باید در حین انجام این ایده پروژه از خود بپرسیم. از دیدگاه مهندسی نرم افزار:

  2. تجزیه و تحلیل نیازمندی: نیاز فوری به داشتن یک مستند مختصر و تلفیقی برای نیازهای ما وجود دارد. فقدان مستندات به چشم‌اندازهای آینده برنامه‌های منبع باز آسیب می‌زند و تا حد زیادی جزء ضروری و غیر قابل چشم پوشی است. پیوند دادن به این اسناد باید یک صفحه اصلی جذاب باشد که در یک لحظه علاقه مردم را جلب می کند. مستندات باید به خوبی سازماندهی شده باشد و در نتیجه جریان یکپارچه را از طریق آن امکان پذیر کند.

  3. مشخصات: بسته به نیاز، مشخصات را می توان تصمیم گرفت. محتوای موجود در مستندات را می توان از داده های موجود در وب سایت های CC netlify، همراه با الهام از اسناد شناخته شده مانند semantic-ui، scikit-learn، numpy، bootstrap و غیره تشکیل داد. خروجی این کار صفحه فرود مورد نیاز خواهد بود. و راهنمای مستندات کامل.

برخی از مسائل کلی مرتبط با Vocabulary، Vue-Vocabulary و Fonts در حال حاضر:

  • عدم وجود مستندات؛ و حتی اگر وجود داشته باشد، بخش هایی از آن در سراسر وب سایت های netlify پراکنده است. این به کاربران، توسعه‌دهندگان یا مشارکت‌کنندگان خارجی اجازه استفاده از کتابخانه ما را نمی‌دهد.

    • برای رسیدن به یک مؤلفه خاص و کپی کردن کد مربوطه، کلیک های اضافی لازم است. یک جستجوی ساده در گوگل برای چیزی مانند "Tabs component CC Vocabulary" اطلاعات مورد نظر را بر نمی گرداند. یک گزینه جستجو در راهنماهای اسناد، UX را تا حد زیادی بهبود می بخشد.

    • توضیحات متنی کمی برای اجزای سازنده، که جزئیات نامشخص را توصیف می کند.

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

راه حل

راه حل های متعددی ممکن است. با این حال، من در اینجا به چند مورد اشاره می کنم و راه حل نهایی خود را در قسمت پایانی ارائه می کنم:

= استفاده از readthedocs readthedocs یک راه حل شناخته شده برای نوشتن اسناد برای کتابخانه های منبع باز است. این بر اساس Sphinx، ابزار مستندسازی پایتون است.

جوانب مثبت:

  1. شکل به طور گسترده پذیرفته شده تولید اسناد، که توسط سازمان هایی مانند اتریوم (Solidity) استفاده می شود.
  2. اسناد بهینه ساختار یافته
  3. هاست استاتیک رایگان

معایب:

  1. عدم کنترل مطلق بر استایل.

= استفاده از Sphinx ما می‌توانیم به صورت بومی از اسفینکس برای بخش مستندات نیز استفاده کنیم، این برنامه ویژگی‌های خوبی را برای همه اهداف ما فراهم می‌کند.

جوانب مثبت:

  1. محبوب ترین ابزار پایتون برای مستندسازی.
  2. پشتیبانی از جستجوی اسناد نیز دارد.
  3. CSS پیش‌فرض را می‌توان با یک سفارشی لغو کرد. برخی از کنترل ها بر HTML با استفاده از فایل های rst.

معایب:

  1. شامل کدنویسی در پایتون و قالب متن بازسازی شده (.rst) می شود که انحراف از زبان های پروژه پیشنهادی است.

= استفاده از تم های Jekyll تم های Jekyll در صفحات github ادغام شده اند و قالب های از قبل موجود وجود دارد که بسته به نیاز ما می توانند سفارشی شوند.

جوانب مثبت:

  1. تم های مستند آماده برای همه مقاصد.
  2. CSS و سبک‌های پیش‌فرض ممکن است با موارد سفارشی، کنترل بر HTML نیز لغو شوند.
  3. CSS پیش‌فرض Primer را برای ساخت صفحات می‌کشد.
  4. ادغام آسان با صفحات GitHub.

معایب:

  1. ممکن است بهترین ساختار اسناد را ارائه نکند.

=استفاده از صفحات GitHub صفحات استاندارد github برای ساخت سایت ثابت ما (HTML، CSS، JS).

جوانب مثبت:

  1. کنترل کامل تقریباً بر همه چیز مورد نظر.
  2. حداکثر انعطاف پذیری در تصمیم گیری در مورد چیدمان، رنگ ها و سبک ها.
  3. استفاده آسان از اجزای واژگان.
  4. جاسازی آسان قطعات کد و پیوندهای اجرای زنده.

معایب:

  1. ممکن است یک رویکرد وقت گیرتر باشد.

= استفاده از Haroopad این یک راه حل جایگزین برای نشانه گذاری می دهد.

جوانب مثبت:

  1. شامل حداقل کد نویسی مبهم است.
  2. تمرکز روی نوشتن کامل اسناد خواهد بود.

معایب:

  1. عدم کنترل CSS
  2. ممکن است بهترین حمایت جامعه را داشته باشد یا نداشته باشد.
  3. ممکن است از MDX پشتیبانی نکند.

= استفاده از MKDocs به جای آن راه حل جایگزین دیگری برای نشانه گذاری ارائه می دهد.

جوانب مثبت:

  1. شامل حداقل کد نویسی بیهوده (دوباره).
  2. بیشتر بنویسید، رویکرد کد کمتر.

معایب:

  1. عدم کنترل CSS
  2. ممکن است بهترین حمایت جامعه را نداشته باشد.
  3. از پایتون استفاده می کند. ممکن است نیاز به چرخش یک نمونه آمازون S3 بیشتر شود.

= استفاده از VueJS +StorybookJS این رویکرد معمولاً در Vocabulary و مخازن خواهر آن استفاده می شود.

جوانب مثبت:

  1. پایبندی به فناوری‌هایی که با توجه به تجربیات کاری گذشته، به خوبی کار می‌کنند.
  2. آشنایی با پایه کد.
  3. هیچ فناوری شایسته ای در این فضا وجود ندارد.

معایب:

  1. گزینه های ساده تری نیز ممکن است برای اهداف مشابه وجود داشته باشد.

در پایان، می‌خواهم فکر کنم رویکردی که شامل رویکرد VueJS+Storybook (HTML، CSS، JS) است، مناسب‌ترین روش به نظر می‌رسد، با توجه به اینکه من نیز با آن راحت هستم. با این حال، این بدان معناست که ما در توسعه این برنامه به طور کامل از راه خود خارج نخواهیم شد. همچنین استفاده از اجزای CC-Vocabulary نیز نسبتاً ساده است. با این حال، برای تصمیم گیری در مورد ساختار مستندات، ما قطعاً باید نحوه تقسیم محتوا بین زیرعنوان در مستندات readthedocs را در نظر بگیریم. وب‌سایت Semantic-UI (که از StoryBook استفاده می‌کند) تحت تأثیر قرار گرفتم، زیرا ظاهری مینیمال دارد و می‌توان به راحتی پس از چند کلیک به آنچه می‌خواهد پی برد. به غیر از Semantic-UI، من همچنین نگاهی به Material Design، Primer، Bootstrap، Carbon Design و غیره داشتم تا به عنوان راهنمای استایل UI و سیستم های طراحی برای کارم استفاده شود. همچنین می‌توانیم تم‌های مستندات آماده جکیل را نیز برای الهام گرفتن از آن جستجو کنیم.