تحتوي هذه الصفحة على تفاصيل مشروع كتابة فني مقبول في موسم Google من المستندات.
ملخّص المشروع
- مؤسسة مفتوحة المصدر:
- National Resource for Network Biology (NRNB)
- الكاتب الفني:
- Prubhtej_9
- اسم المشروع:
- إنشاء مستندات للمستخدمين في SynBioHub وتطوير أدلة تعليمية لحالات استخدام معيّنة
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
ملخص
تم تصميم مستندات المستخدمين لمساعدة المستخدمين النهائيين على استخدام منتج أو خدمة. إنّ مستندات المستخدمين الجيدة مهمة جدًا لأنّها توفّر للمستخدمين طريقة لمعرفة كيفية استخدام البرنامج وميزاته ونصائحه وحيل استخدامه، بالإضافة إلى حلّ المشاكل الشائعة التي يواجهونها عند استخدام البرنامج. ويقلل أيضًا تكاليف الدعم ويشكّل جزءًا من هوية الشركة للمنتج، أي أنّ مستندات المستخدم الجيدة تشير إلى أنّ المنتج سليم وفريق المطوّرين. بدون توفّر مستندات جيدة للمستخدم، قد لا يعرف المستخدم كيفية تنفيذ الإجراءات المذكورة أعلاه بفعالية وكفاءة. يمكن أن تؤدي مستندات المستخدمين دورًا محوريًا في ضمان نجاح المنتج، لأنّ التواصل الجيد هو أساس أي نشاط تجاري أو منتج، وسيظل كذلك دائمًا، وتأخذ المستندات الجيدة هذا التواصل وتضعه في إطار عمل يمكن للجميع الوصول إليه لتحقيق النجاح. SynBioHub هو مستودع تصميم لعلم الأحياء الاصطناعي. وهو متاح كموقع إلكتروني متاح للجميع وكبرنامج مفتوح المصدر. يستخدم SynBioHub لغة Synthetic Biology Open Language (SBOL)، وهي معيار مفتوح المصدر لتمثيل التصاميم الجينية، كما يسمح بمشاركة أجزاء التصميم من ملفَي GenBank وFASTA. يمكن استخدام SynBioHub لنشر مكتبة من الأجزاء والتصاميم الاصطناعية كخدمة، ولمشاركة التصاميم مع المتعاونين، ولحفظ تصاميم الأنظمة البيولوجية على الجهاز. يمكن الوصول إلى البيانات في SynBioHub من خلال واجهة برمجة التطبيقات HTTP API أو Java API أو Python API، حيث يمكن بعد ذلك دمجها في أدوات التصميم بمساعدة الكمبيوتر (CAD) لإنشاء تصاميم جينية. يحتوي SynBioHub على واجهة تتيح للمستخدمين تحميل بيانات بيولوجية جديدة إلى قاعدة البيانات، وعرض أجزاء الحمض النووي، وإجراء طلبات بحث للوصول إلى الأجزاء المطلوبة، وتنزيل 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 على بعض المستندات التي ترتبط فقط بواجهة برمجة التطبيقات، في حين لا تتوفّر أي مستندات لواجهة المستخدم الرسومية.
الحالة الحالية للمستندات:
في الوقت الحالي، تتوفّر وثائق المستخدم على الرابط التالي: "https://synbiohub.github.io/api-docs/#about-synbiohub ". هذه ليست سوى مستندات واجهة برمجة التطبيقات ولا تتوفّر مستندات واجهة المستخدم الرسومية التي يمكن أن تساعد المستخدم في التنقّل داخل مستودع التصميم. تحتاج أيضًا مستندات واجهة برمجة التطبيقات إلى بعض التعديلات، مع تضمين بعض المواضيع المحدّدة، مثل تحديد المشاكل الغريبة التي قد يواجهها المستخدم وحلّها. سجّلت المؤسسة بعض الفيديوهات التعليمية، مثل الفيديو المتوفّر هنا. لا تتوفّر مستندات مكتوبة للمستخدمين حول SynBioHub يمكنها إرشادهم.
ما هي التحسينات التي تحقّقها مستندات المستخدم المقترَحة مقارنةً بالمستندات الحالية؟ سأقوم بإنشاء وثائق واجهة المستخدم الرسومية من البداية باستخدام GitHub وMarkdown كما يقترح المرشد، السيد كريس مايرز. سيتم تنظيم مستندات المستخدم المقترَحة لتحسين الكفاءة والاتساق والطمأنينة لأي مستخدم نهائي. وسيتضمّن هذا الدليل أدلة مكتوبة وصورًا مرتبطة بها، بالإضافة إلى تعليمات وشرح حول كيفية استخدام كل ميزة من ميزات المحاكي المفتوح المصدر SynBioHub. خلال المناقشات مع السيد "مايرز"، تم أيضًا اتخاذ قرار بدمج مستندات واجهة برمجة التطبيقات مع واجهة المستخدم وستتضمّن 6 أقسام، وسيكون القسم السادس اختياريًا. يتم ذكر الأقسام على النحو التالي: 1. المقدّمة 2 تعليمات التثبيت أ) من صورة مُعدّة مسبقًا ب) من المصدر ج) إعدادات NGINX 3. إرشادات المستخدم أ) إرشادات مفصلة حول كيفية استخدام كل ميزة من ميزات واجهة المستخدم الرسومية ب) برامج تعليمية لحالات الاستخدام الشائعة 4. وثائق واجهة برمجة التطبيقات - القسم 5 من نقاط النهاية. وثائق المكونات الإضافية 6. تحديد المشاكل وحلّها والمراجع المستقبلية
الجزء 1:
في هذا القسم، سيتم تزويد المستخدمين بمقدمة مفصّلة وبرامج تعليمية متنوعة في ما يتعلق بـ SynBioHub.
الجزء 2:
في هذا القسم، يتم توضيح الطرق المختلفة التي يمكن للمستخدم من خلالها تثبيت البرنامج المفتوح المصدر باستخدام طرق مختلفة، وهي: أ) من صورة مُعدّة مسبقًا ب) من المصدر ج) إعدادات NGINX
الجزء 3:
هذا هو الجزء الأكثر أهمية في المستندات وسيستغرق معظم الوقت. في ما يلي، ستتم إضافة كل التفاصيل الدقيقة في سياق واجهة المستخدم. وكما أسلفنا أعلاه، سنتناول في هذا القسم مشكلتين أساسيتين، أي التعليمات التفصيلية حول كيفية استخدام كل ميزة من ميزات واجهة المستخدم الرسومية وبعض البرامج التعليمية لحالات الاستخدام الشائعة.
الجزء 4:
كما ذكرنا أعلاه، سيتم استخدام Slate لإنشاء مستندات هذا الجزء. في هذا القسم، سيتم تضمين نقاط النهاية التالية: 1. نقاط نهاية المستخدم 2- نقاط نهاية البحث 3. تنزيل نقاط النهاية 4- تنزيل نقاط النهاية 5- نقاط نهاية الإرسال 6. نقاط نهاية الأذونات 7- تعديل نقاط النهاية 8. نقاط نهاية المرفقات 9. نقاط نهاية الإدارة
الجزء 5:
في هذا القسم، سيتم تضمين مستندات المكوّن الإضافي المتوفّرة حاليًا في مستندات SynBioHub القديمة. سيتم تقسيم هذا القسم إلى قسمَين، وهما: مواصفات المكوّن الإضافي وتنفيذه. الجزء السادس: [اختياري] سيتضمّن هذا القسم قائمة شائعة جدًا بالأخطاء التي يواجهها المستخدمون، كما يتضمّن بعض تعليمات تحديد المشاكل وحلّها. وفقًا للمناقشة مع السيد "مايرز"، تمّ الاتفاق على دمج هذا القسم مع قسم المقدمة، إذا لم يكن ذلك طويلاً جدًا. التحليل أجريت أنا والسيد مايرز محادثة حول كيفية تحديث الوثائق الحالية وكذلك كتابة مستند جديد لواجهة المستخدم الرسومية . خلال هذه المحادثات القليلة، وضعنا تنسيقًا أساسيًا للمستندات الجديدة المذكورة أعلاه، وتم تقديم مخطط زمني تقديري في الصفحة 5 أدناه. وفقًا للمناقشة، سأستخدم GitHub وMarkdown لإنشاء المستندات لكل قسم باستثناء الجزء 4 من المستندات الذي سيتم فيه استخدام Slate. Slate:- يساعدك Slate في إنشاء مستندات واجهة برمجة التطبيقات جميلة وذكية ومتوافقة مع الأجهزة الجوّالة. Slate هي أداة مستندة إلى Ruby تعمل على إنشاء موقع إلكتروني ثابت لمستندات واجهة برمجة التطبيقات يضم ثلاث لوحات ويمتاز بمظهر رائع من مجموعة من ملفات Markdown. أنشأه المطوّر "روبرت لورد" في عام 2013 عندما كان متدربًا في سن 18 عامًا في شركة Tripit لبرامج السفر. أقنع رئيسه في ذلك الوقت بالسماح له بفتح مصدر المشروع، وأصبح المشروع مشهورًا. وتتضمّن الميزات التالية: • تصميم بسيط وسهل الاستخدام: باستخدام Slate، يظهر وصف واجهة برمجة التطبيقات على يمين المستندات، وتظهر جميع أمثلة الرموز البرمجية على يمين الصفحة. مستوحاة من مستندات واجهة برمجة التطبيقات في Stripe وPayPal يتسم Slate بسرعة الاستجابة، لذا يبدو رائعًا على الأجهزة اللوحية والهواتف، وحتى في الطباعة. • أصبح كل شيء في صفحة واحدة: لقد اختفت الأيام التي اضطر فيها المستخدمون إلى البحث في ملايين الصفحات للعثور على ما يريدون. يضع Slate الوثائق بأكملها في صفحة واحدة. مع ذلك، لم نتخلّ عن إمكانية الربط. أثناء الانتقال للأعلى أو للأسفل، سيتم تعديل التجزئة في المتصفّح إلى أقرب عنوان، ما يضمن سهولة الربط بنقطة معيّنة في المستندات. • Slate هو تنسيق Markdown فقط: عند كتابة مستندات باستخدام Slate، ما عليك سوى كتابة Markdown، ما يسهّل تعديلها وفهمها. تتم كتابة كل شيء باستخدام Markdown، حتى أنّ عيّنات الرموز البرمجية ليست سوى مجموعات رموز Markdown. • كتابة عيّنات رموز برمجية بلغات متعددة: إذا كانت واجهة برمجة التطبيقات تتضمّن عمليات ربط بلغات برمجة متعددة، يمكنك بسهولة إدراج علامات تبويب للتبديل بينها. في المستند، ستميّز اللغات المختلفة من خلال تحديد اسم اللغة في أعلى كل مجموعة رموز، تمامًا كما هو الحال في GitHub Flavored Markdown. • ميزة تمييز البنية المتوفّرة تلقائيًا لأكثر من 100 لغة، بدون الحاجة إلى ضبط أي إعدادات • جدول محتويات يتيح الانتقال السلس للأعلى أو للأسفل تلقائيًا في أقصى يمين الصفحة أثناء الانتقال للأعلى أو للأسفل، يتم عرض موضعك الحالي في المستند. وهو سريع أيضًا. نستخدم Slate في TripIt لإصدار وثائق لواجهة برمجة التطبيقات الجديدة، حيث يحتوي جدول المحتويات على أكثر من 180 إدخالاً. لقد تأكّدنا من بقاء الأداء ممتازًا، حتى في المستندات الأكبر حجمًا. • السماح للمستخدمين بتعديل وثائقك نيابةً عنك: تتم تلقائيًا استضافة المستندات التي تم إنشاؤها من خلال واجهة رمادية في مستودع GitHub العام. وهذا لا يعني حصولك على استضافة مجانية لمستنداتك باستخدام صفحات GitHub، كما يسهّل على المطوّرين الآخرين تقديم طلبات سحب إلى مستنداتك عند عثورهم على أخطاء إملائية أو مشاكل أخرى. بالطبع، إذا كنت لا ترغب في استخدام GitHub، فنحن نرحب أيضًا باستضافة مستنداتك في أي مكان آخر. • التوافق مع التنسيق من اليمين إلى اليسار للّغات التي تستخدم التنسيق من اليمين إلى اليسار، مثل العربية والفارسية (الفارسية) والعبرية، وما إلى ذلك. يعدّ Verdict Slate أحد أقوى البرامج مفتوحة المصدر لإنشاء المستندات ووفقًا للمناقشات التي أناقشها مع مرشدي، السيد كريس مايرز، سأستخدم العناصر الحاجبة للجزء الرابع، وبالنسبة إلى أجزاء أخرى، سيتم استخدام github وMarkdown. يتمّ مناقشة عرض أكثر تفصيلاً للمستندات في الأقسام أدناه. بنية المستندات المقترَحة: لقد أنشأت بنية لدليل مستخدم SynBioHub الذي يمكن العثور عليه في الصفحة 2. تم قبول هذه البنية، وقد عدّلها السيد "مايرز". أهداف المشروع 1. إعادة هيكلة الوثائق. 2. يُرجى تعديل المستندات لتلائم الإصدارات الحديثة من SynBioHub. 3- أزِل المعلومات القديمة. 4. إعادة كتابة مستندات المستخدمين لتسهيل فهمها 5- قم بتضمين قسم موجز للمتطلبات المسبقة إلى الوثائق الخاصة بالمساهمين الجدد حتى يتسنى لهم زيادة فهمهم الأساسي للمفاهيم البيولوجية الأساسية وواجهة SynBioHub.