تحتوي هذه الصفحة على تفاصيل مشروع كتابة تقنيّة تم قبوله في موسم المستندات من Google.
ملخص المشروع
- المؤسسة المفتوحة المصدر:
- DIPY
- الكاتب التقني:
- أريشا طارق
- اسم المشروع:
- إعادة الهيكلة رفيعة المستوى وتركيز المستخدمين النهائيين
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
أنا مهندس برمجيات ولدي خبرة في الكتابة الفنية. لدي أكثر من 4 سنوات من الخبرة في كتابة وثائق البرامج عالية الجودة وأدلة المستخدم والكتيبات وأوصاف المشروعات. أقيم في إسلام آباد، باكستان (المنطقة الزمنية: التوقيت العالمي المنسَّق + 5). أعمل حاليًا كمتدرب في مجال التواصل الاجتماعي وستستمر حتى 18 آب (أغسطس). لقد شاركت في Google Season of Docs ككاتبة فنية في مؤسسة OpenELIS Global. كانت المستندات الأصلية باللغة الفرنسية، محدودة، وقديمة، لذا أنشأت مستندات شاملة ومحدّثة للمستخدمين النهائيين باللغة الإنجليزية. تم اختياري في مبادرة Outreachy في مؤسستَي Perl & Raku في جولة أيار (مايو) إلى آب (أغسطس) 2020 كمطوّر خلفية لخادم Open Food Facts. إلى جانب تطوير الواجهة الخلفية، تتمثل إحدى المهام الرئيسية لهذا التدريب في إنشاء وثائق للوحدات والوظائف بتنسيق POD. لقد دخلت إلى عالم البرامج المفتوحة المصدر في العام الماضي عندما ساهمت في بعض المشروعات مفتوحة المصدر وشاركت لاحقًا في Google Season of Docs. وهذا العام، تم اختياري في قسم التوعية الذي يدعم التنوع في البرامج المفتوحة المصدر والبرامج المجانية. لديّ سيطرة قوية على Git حيث تتم استضافة مشروع التوعية الخاص بي على GitHub، وقمت بتقديم مساهمات منتظمة في منظمة Open Food Facts وMozilla Fenix منذ آذار (مارس). أنا أستخدم نظام التشغيل Linux منذ أكثر من 3 سنوات وأستخدم أوامر الأوامر الطرفية منذ ذلك الحين.
أدوات التوثيق واللغات التي استخدمتها هي Sphinx وRead the docs و Markdown. لقد أحببت هذه الفكرة وأريد العمل عليها لأن لدي خبرة ذات صلة وأرغب في استخدام معرفتي ومهاراتي للمساهمة في DIPY. لدي خبرة في مجال معالجة الصور الرقمية والرؤية الحاسوبية والتعلم الآلي. ستساعدني في فهم التصوير العصبي بشكل أفضل وتساعدني في إنشاء المستندات. لدي خبرة واسعة في المجال الطبي. لقد أنشأت موقعًا إلكترونيًا طبيًا للأطباء والمرضى والمختبرات وسائقي سيارات الإسعاف. عملت على نظام آخر استخدمه الأطباء والمرضى والممرضون ومساعدو المختبر والباحثون. سيساعدني ذلك في إنشاء وثائق يسهل فهمها من قبل الجمهور.
لقد راجعتُ المستندات الخاصة بشركة DIPY ولاحظت العديد من العيوب في الوثائق. هناك ثغرات متعددة في الوثائق التي أخطط لتحسينها. الحالة الحالية للوثائق: تفتقر الوثائق إلى هيكل وتصميم محددين قد تكون مملة وتستغرق وقتًا طويلاً، خاصة بالنسبة إلى المستخدمين الجدد للتنقل قد يواجه المستخدمون صعوبة في الحصول على المعلومات من الدليل يحتاج محتوى الوثائق إلى تحسين بصفتي مستخدمًا جديدًا، وجدت أنه من الصعب الوصول إلى دليل المستخدم ودليل المطور. يجب إعادة صياغة الوثائق بطريقة تجعل المعلومات التي يحتاجها المستخدم يسهل الوصول إليها تفتقر المستندات إلى الاتساق
أنوي إجراء ما يلي:
تحديد هيكل وقالب معين للوثائق إعادة تشكيل الوثائق بحيث يمكن للمستخدمين التنقل بسهولة والعثور على المعلومات المطلوبة إنشاء خارطة طريق أو قائمة بنود العمل لجذب المجتمع إلى المزيد من أعمال التوثيق تحديد نماذج لدليل المستخدم ودليل المطور تحديد نماذج لدليل المساهمة إعادة كتابة دليل المستخدم وإعادة هيكلة وتحديث دليل المستخدم ودليل التطوير والمساهمة (التي يمكن أن تساعد في تحسين الوثائق النصية الجديدة وتحفيز المستخدمين الجدد) تحسين الوثائق النصية الجديدة
دليل المستخدم:
بالنسبة لدليل المستخدم، أود أن أركز على استخدام لغة بسيطة وعادية لمساعدة المستخدمين على فهم حتى أكثر الأنظمة تعقيدًا. سيتم تجنب المصطلحات الاصطلاحية والاختصارات وغيرها من المعلومات الداخلية التي قد لا يعرفها المستخدم الجديد لتحسين تجربة المستخدم. سأركز أيضًا على استخدام المحتوى المرئي، بما في ذلك الصور ولقطات الشاشة التوضيحية والرسومات ومقاطع الفيديو، والتي توضح للمستخدم بسرعة كيفية عمل النظام. يحتاج التوثيق الجيد إلى تسلسل هرمي من العناوين والعناوين الفرعية يتيح للمستخدم معرفة ما سيعرضه كل قسم. ويجب أن يتبع هذا التسلسل الهرمي تدفقًا منطقيًا يساعد المستخدم على تعلم استخدام النظام بالطريقة الأكثر فائدة. سيكون أحد الأهداف الرئيسية لهذا المشروع هو إنشاء محتوى يمكن الوصول إليه. ستتقيد جميع الوثائق والأدلة بأسلوب متسق. يجب استخدام خطوط متناسقة وألوان تكميلية في مستندات متعددة. سأتأكد من أن المستخدمين لديهم إمكانية الوصول إلى المزيد من موارد المؤسسة حول كيفية النجاح مع النظام.
دليل المطوِّر:
يتضمن دليل المطور إرشادات شاملة ومواد مرجعية لمساعدة المطور في تقديم المساهمات إلى التعليمات البرمجية المصدر لـ DIPY. حيث يحاول وضع الخيارات المختلفة المتاحة لك، حتى تتمكن من استخدام النهج الصحيح، اعتمادًا على ما تريد تحقيقه. يحتاج دليل التطوير إلى إعادة تشكيل وإعادة الهيكلة. سأعيد كتابة محتوى دليل المطوِّر. سيتم تضمين عناصر إنشاء التبعيات ودليل المساهمة ودليل الأسلوب واصطلاحات الترميز ودليل الوثائق وتثبيت بيئة التطوير وتصحيح الأخطاء ودليل الاختبار والعناصر ذات الصلة وتسهيل دخول المطورين إليها. عندما يندفع المساهمون الجدد المتحمسون إلى مشروعك لتقديم أول مساهمة مفتوحة المصدر لهم، فإنهم يعتمدون على إرشادات المساهمة لتكون مساعدتهم الإرشادية. وبالتالي ستكون الإرشادات سهلة القراءة وشاملة وودية. تعد أدلة المساهمة وثائق مفيدة توضح كيف يمكن للأشخاص المساهمة في المشروع مفتوح المصدر. يجب أن تكون المساهمة في المشروع سهلة وشفافة قدر الإمكان للمستخدمين، سواء كان ذلك: إرسال إصلاح الإبلاغ عن خطأ تولي دور صيانة مناقشة الحالة الحالية للرمز اقتراح ميزات جديدة
TEMPLATE
وهذا أحد النماذج التي يمكن استخدامها في دليل المساهمة. ويمكن تعديله وإضافة أقسام أو إزالتها وفقًا لمتطلبات المستند.
المساهمة في DIPY
- كلمة ترحيبية
جدول المحتويات
مدوّنة السلوك
- معاييرنا
- أمثلة على السلوك الذي يساهم في خلق بيئة إيجابية
- أمثلة على سلوك غير مقبول من جانب المشاركين
- مسؤولياتنا
- مسئوليات الحفاظ على المشروع
- النطاق
نطاق مدوّنة السلوك
ما هي المعلومات التي يجب معرفتها للمساعدة؟
إذا كنت تريد المساعدة في المساهمة بالرمز التي يستخدمها مشروعنا [إدراج قائمة بلغات البرمجة أو أُطر العمل أو الأدوات التي يستخدمها مشروعك]. إذا لم تكن مستعدًا بعد لتقديم رمز المساهمة، لا مشكلة. يمكنك أيضًا التحقق من مشكلات الوثائق [رابط إلى تصنيف المستندات أو العلامة على أداة تتبع المشكلات] أو مشكلات التصميم التي لدينا [رابط إلى تصنيف التصميم أو العلامة على أداة تتبع المشكلات إذا كان مشروعك يتتبع مشكلات التصميم]. إذا كنت مهتمًا بتقديم رمز المساهمة ومعرفة المزيد من المعلومات حول التكنولوجيا التي نستخدمها، يمكنك الاطّلاع على القائمة أدناه. قم بتضمين قائمة نقطية بالموارد (البرامج التعليمية ومقاطع الفيديو والكتب) التي يمكن للمساهمين الجدد استخدامها لمعرفة ما يحتاج المستخدمون إلى معرفته للمساهمة في المشروع.
إعداد بيئة التطوير
في هذا القسم، سأضيف إجراء التثبيت والتبعيات التي ينبغي تثبيتها. تثبيت $project من خلال التشغيل: تثبيت المشروع
- رمز المصدر: github.com/$project/$project
- أداة تتبُّع المشاكل: github.com/$project/$project/issues
كيفية المساهمة
كيفية الإبلاغ عن خطأ
- قبل إرسال تقرير خطأ
- كيف يمكنني إرسال تقرير خطأ (جيد)؟
كيفية إرسال التغييرات
- بروتوكولات طلب السحب
- رد من الفريق
- سرعة الاستجابة
كيفية طلب تحسين
- قبل إرسال اقتراح التحسين
- كيف يمكنني إرسال اقتراح تحسين (جيد)؟
مساهمتك الأولى في الرمز
- مشاكل للمبتدئين
- مشكلات المساعدة المطلوبة #### طلب السحب
- عملية إنشاء طلب السحب
- تأكَّد من اجتياز جميع عمليات التحقّق من الحالة.
ماذا لو تعذّر إتمام عمليات التحقّق من الحالة؟
- اختبارات كتابة
- تغطية الاختبار
دلائل الأسلوب
- رسائل تنفيذ Git
- النمط العادي
الدعم
إذا كنت تواجه مشاكل، يُرجى إبلاغنا بها. إذا كنت بحاجة إلى مساعدة، يمكنك طرح أسئلة على قائمتنا البريدية على العنوان: project@google-groups.com، أو محادثة IRC، أو [إدراج أي منصات اتصال أخرى يستخدمها مشروعك].
الترخيص
سيتناول هذا القسم معلومات حول ترخيص المشروع.
الالتزام بالوقت والتواصل:
سأخصص 45 ساعة أو أكثر في الأسبوع، ولكن في حال حدوث أي حادث، سأعوض عن هذه الساعات في عطلات نهاية الأسبوع. خلال فترة الترابط بين أفراد المنتدى، سأناقش وسائل التواصل وسأنهي الاجتماعات الأسبوعية والوسائل والوقت لتلك الاجتماعات مع مرشدي. سأبقي مرشدي على اطلاع دائم حول عملي؛ وسأشارك تفاصيل عملي عبر البريد الإلكتروني مع مرشدي. سأفضِّل TeamViewer للتواصل، حيث أنه سهل الاستخدام مع الكثير من الميزات مثل مشاركة الشاشات وما إلى ذلك.