این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه پروژه
- سازمان منبع باز:
- منبع ملی بیولوژی شبکه (NRNB)
- نویسنده فنی:
- Prubhtej_9
- نام پروژه:
- مستندات کاربر را برای SynBioHub ایجاد کنید و آموزش هایی را برای موارد استفاده خاص ایجاد کنید
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
چکیده
مستندات کاربر برای کمک به کاربران نهایی برای استفاده از یک محصول یا خدمات طراحی شده است. مستندات خوب کاربر بسیار مهم است زیرا راهی را برای کاربران فراهم می کند تا نحوه استفاده از یک نرم افزار، ویژگی ها، نکات، ترفندهای آن را بیاموزند و همچنین مشکلات رایجی که هنگام استفاده از نرم افزار با آن مواجه می شوند را حل کنند. همچنین هزینه پشتیبانی را کاهش می‌دهد و بخشی از هویت شرکتی محصول است، یعنی مستندات کاربری خوب نشانه‌ای از محصول سالم و تیم توسعه‌دهنده است. بدون مستندات کاربر خوب، کاربر ممکن است نداند که چگونه کارهایی را که در بالا ذکر شد به طور موثر و کارآمد انجام دهد. اسناد کاربر می تواند نقشی اساسی در تضمین موفقیت یک محصول داشته باشد زیرا ارتباطات عالی همیشه در قلب هر کسب و کار یا محصولی وجود دارد و خواهد بود و یک مستندات عالی فقط آن ارتباط را می گیرد و آن را در یک چارچوب قابل مدیریت قرار می دهد که همه می توانند برای موفقیت به آن دسترسی داشته باشند. SynBioHub یک مخزن طراحی برای زیست شناسی مصنوعی است. این هم به عنوان یک وب سایت عمومی و هم به عنوان نرم افزار منبع باز در دسترس است. SynBioHub از زبان باز زیست شناسی مصنوعی (SBOL) استفاده می کند، یک استاندارد منبع باز برای نمایش طرح های ژنتیکی، و همچنین اجازه می دهد تا قطعات طراحی را از GenBank و فایل های FASTA به اشتراک بگذارد. SynBioHub می تواند برای انتشار یک کتابخانه از قطعات مصنوعی و طرح ها به عنوان یک سرویس، برای به اشتراک گذاشتن طرح ها با همکاران، و برای ذخیره طرح های سیستم های بیولوژیکی به صورت محلی استفاده شود. داده‌ها در SynBioHub می‌توانند از طریق HTTP API، Java API یا Python دسترسی داشته باشند و سپس می‌توانند در ابزارهای CAD برای ساخت طرح‌های ژنتیکی ادغام شوند. SynBioHub شامل یک رابط برای کاربران برای آپلود داده های بیولوژیکی جدید در پایگاه داده، تجسم قطعات DNA، انجام پرس و جو برای دسترسی به قسمت های مورد نظر، و دانلود SBOL، GenBank، FASTA و غیره است. مقالات تحقیقاتی مختلف و برخی آموزش ها نیز در اینترنت مانند: 1. https://pubs.acs.org/doi/abs/10.1021/acssynbio.7b00403 2. https://pubs.acs.org/doi/abs/10.1021/acssynbio.0c00056 SynBioHub اسنادی دارد که فقط درباره آن صحبت می کنیم مربوط به API است در حالی که هیچ سندی برای رابط کاربری گرافیکی وجود ندارد.
وضعیت فعلی اسناد:
در حال حاضر، اسناد کاربر در این آدرس موجود است: "https://synbiohub.github.io/api-docs/#about-synbiohub". این فقط مستندات API است و مستندات رابط کاربری گرافیکی وجود ندارد که می تواند به کاربر کمک کند تا در مخزن طراحی حرکت کند. همچنین اسناد API به کمی به روز رسانی نیز نیاز دارد، با برخی موضوعات خاص مانند عیب یابی برخی از مسائل عجیب و غریب که ممکن است یک کاربر با آن مواجه شود. در حالی که سازمان برخی از فیلم های آموزشی را ضبط کرده است، مانند آنچه در اینجا وجود دارد. در واقع هیچ سند مکتوب کاربر در مورد SynBioHub وجود ندارد که بتواند کاربر را راهنمایی کند.
چرا اسناد کاربر پیشنهادی شما نسبت به سند فعلی بهبود یافته است؟ من مستندات رابط کاربری گرافیکی را از ابتدا با استفاده از github و markdown می‌سازم که توسط مربی، آقای کریس مایرز پیشنهاد شده است. اسناد کاربر پیشنهادی برای بهبود و اطمینان از کارایی، سازگاری و آرامش خاطر برای هر کاربر نهایی ساختاربندی خواهد شد. این شامل راهنماهای مکتوب و تصاویر مرتبط با آن، شامل دستورالعمل‌ها و توضیح در مورد نحوه استفاده از هر ویژگی شبیه‌ساز منبع باز SynBioHub است. در طول بحث با آقای مایرز، همچنین تصمیم گرفته شد که اسناد API با رابط کاربری گرافیکی ادغام شود و شامل 6 بخش باشد که از این میان بخش 6 اختیاری است. بخش ها به شرح زیر ذکر شده اند: 1. مقدمه 2. دستورالعمل های نصب الف) از تصویر از پیش ساخته شده ب) از منبع ج) پیکربندی NGINX 3. دستورالعمل های کاربر الف) دستورالعمل های دقیق در مورد نحوه استفاده از هر ویژگی رابط کاربری گرافیکی ب) آموزش برای موارد استفاده رایج 4 API Documentation - Endpoints بخش 5. Plugin Documentation .
قسمت 1:
در این بخش، معرفی دقیق و آموزش های مختلف در رابطه با SynBioHub در اختیار کاربران قرار می گیرد.
قسمت 2:
در این بخش راه های مختلفی که کاربر می تواند با استفاده از روش های مختلف نرم افزار متن باز را نصب کند، به شرح زیر است: الف) از تصویر از پیش ساخته شده ب) از منبع ج) پیکربندی NGINX.
قسمت 3:
این مهم ترین بخش مستندات است و بیشتر زمان را به خود اختصاص می دهد. در اینجا، هر دقیقه جزئیات در زمینه به رابط کاربری گرافیکی اضافه خواهد شد. همانطور که در بالا ذکر شد، در این بخش عمدتاً به دو نگرانی پرداخته می شود، یعنی دستورالعمل های دقیق در مورد نحوه استفاده از هر ویژگی رابط کاربری گرافیکی و برخی آموزش ها برای موارد استفاده رایج.
قسمت 4:
همانطور که در بالا ذکر شد برای تولید مستندات این قسمت از تخته سنگ استفاده خواهد شد. در این بخش نقاط پایانی زیر گنجانده خواهد شد: 1. نقاط پایانی کاربر 2. نقاط پایانی جستجو 3. نقاط پایانی دانلود 4. نقاط پایانی دانلود 5. نقاط پایانی ارسال 6. نقاط پایانی مجوز. 7. ویرایش نقاط پایانی 8. نقاط پایانی پیوست 9. نقاط پایانی مدیریت
قسمت 5:
در این بخش، مستندات افزونه که قبلاً در اسناد قدیمی SynBioHub وجود دارد، گنجانده خواهد شد. این بخش به دو بخش تقسیم می شود: مشخصات و پیاده سازی افزونه. قسمت-6: [اختیاری] این بخش شامل فهرست بسیار متداولی از خطاهایی است که کاربران با آن مواجه می شوند و همچنین شامل برخی دستورالعمل های عیب یابی است. با توجه به بحث با آقای مایرز، تصمیم گرفته شده است که این بخش را می توان با بخش مقدمه ادغام کرد، اگر خیلی طولانی نشد. تجزیه و تحلیل من و آقای مایرز در مورد نحوه به روز رسانی اسناد موجود و همچنین نوشتن یک سند جدید برای رابط کاربری گرافیکی صحبت کردیم. در آن چند مکالمه، ما یک طرح اولیه برای اسناد جدید که در بالا ذکر شد و یک جدول زمانی تخمینی در صفحه 5 در زیر ارائه شده است، فرموله کردیم. طبق بحث، من از github و markdown برای ساخت مستندات برای هر بخش استفاده می‌کنم، به جز قسمت 4 اسناد که در آن تخته سنگ استفاده می‌شود. Slate: - Slate به شما کمک می کند اسناد API زیبا، هوشمند و پاسخگو ایجاد کنید. Slate یک ابزار مبتنی بر روبی است که یک سایت ثابت API با ظاهر عالی و سه پانل از مجموعه ای از فایل های علامت گذاری ایجاد می کند. این توسط توسعه دهنده رابرت لرد در سال 2013 زمانی که او یک کارآموز 18 ساله در شرکت نرم افزار مسافرتی "Tripit" بود ساخته شد. او در آن زمان رئیس خود را متقاعد کرد که به او اجازه دهد پروژه را منبع باز کند و بقیه آن تاریخ است. این ویژگی‌های زیر را دارد: • طراحی تمیز و بصری - با Slate، توضیحات API شما در سمت چپ اسناد شما قرار دارد و همه نمونه‌های کد در سمت راست هستند. با الهام از اسناد API Stripe و PayPal. Slate پاسخگو است، بنابراین در تبلت ها، تلفن ها و حتی در چاپ عالی به نظر می رسد. • همه چیز در یک صفحه — روزهایی که کاربران شما مجبور بودند در میلیون ها صفحه جستجو کنند تا آنچه را که می خواستند پیدا کنند، گذشته است. Slate کل اسناد را در یک صفحه قرار می دهد. اگرچه ما پیوند پذیری را قربانی نکرده ایم. همانطور که پیمایش می کنید، هش مرورگر شما به نزدیکترین هدر به روز می شود، بنابراین پیوند دادن به یک نقطه خاص در اسناد هنوز طبیعی و آسان است. • Slate فقط Markdown است — وقتی اسناد را با Slate می نویسید، فقط Markdown را می نویسید، که ویرایش و درک آن را ساده می کند. همه چیز در Markdown نوشته شده است - حتی نمونه کدها فقط بلوک های کد Markdown هستند. • نوشتن نمونه کد به چندین زبان — اگر API شما دارای پیوندهایی در چندین زبان برنامه نویسی است، می توانید به راحتی برگه ها را برای جابجایی بین آنها قرار دهید. در سند خود، مانند GitHub Flavored Markdown، با تعیین نام زبان در بالای هر بلوک کد، زبان های مختلف را متمایز خواهید کرد. • برجسته کردن نحو خارج از جعبه برای بیش از 100 زبان، بدون نیاز به پیکربندی. • پیمایش خودکار فهرست مطالب در سمت چپ صفحه. همانطور که پیمایش می کنید، موقعیت فعلی شما را در سند نشان می دهد. سریع هم هست ما از Slate در TripIt برای ایجاد اسناد برای API جدید خود استفاده می کنیم، جایی که فهرست مطالب ما دارای بیش از 180 ورودی است. ما مطمئن شده‌ایم که عملکرد، حتی برای اسناد بزرگ‌تر، عالی باقی می‌ماند. • به کاربران خود اجازه دهید اسناد شما را برای شما به روز کنند — به طور پیش فرض، اسناد تولید شده توسط Slate شما در یک مخزن عمومی GitHub میزبانی می شود. این نه تنها به این معنی است که شما میزبانی رایگان برای اسناد خود با صفحات GitHub دریافت می‌کنید، بلکه باعث می‌شود توسعه‌دهندگان دیگر در صورت یافتن اشتباهات تایپی یا مشکلات دیگر، درخواست‌های کششی را برای اسناد شما ارسال کنند. البته، اگر نمی‌خواهید از GitHub استفاده کنید، می‌توانید اسناد خود را در جای دیگری میزبانی کنید. • پشتیبانی از RTL طرح‌بندی کامل از راست به چپ برای زبان‌های RTL مانند عربی، فارسی (فارسی)، عبری و غیره. کریس مایرز من از تخته سنگ برای قسمت-4 استفاده می کنم و برای قسمت های دیگر از github و markdown استفاده می شود. نمای دقیق تری از مستندات در بخش های زیر مورد بحث قرار گرفته است. ساختار اسناد پیشنهادی من ساختاری برای راهنمای کاربر SynBioHub ایجاد کردم که در صفحه 2 یافت می شود. این ساختار پذیرفته شده است و قبلاً توسط آقای Myers اصلاح شده است. اهداف پروژه 1. بازسازی اسناد. 2. اسناد را متناسب با نسخه های مدرن SynBioHub به روز کنید. 3. اطلاعات منسوخ را حذف کنید. 4. اسناد کاربر را بازنویسی کنید تا درک آن آسان تر شود. 5. یک بخش پیش نیاز مختصر را در اسناد برای مشارکت کنندگان جدید قرار دهید تا درک اولیه آنها از مفاهیم اولیه بیولوژیکی و رابط SynBioHub افزایش یابد.