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