تحتوي هذه الصفحة على تفاصيل مشروع كتابة تقنيّة تم قبوله في موسم المستندات من Google.
ملخص المشروع
- المؤسسة المفتوحة المصدر:
- ESLint
- الكاتب التقني:
- الخوار
- اسم المشروع:
- إعادة تنظيم/إعادة كتابة مستندات الإعدادات
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
تجريدي
الهدف من هذا المشروع هو إعادة هيكلة وثائق الإعدادات لـ ESLint وإنشاء بنية معلومات فعالة. فهذا سيجعل التنقل أسهل ويحسن أيضًا سهولة استخدام الوثائق والاستفادة منها.
ملخّص المشروع تقدّم وثائق إعداد ESLint (https://eslint.org/docs/user-guide/configring)، في الحالة الراهنة، معلومات كثيرة في صفحة واحدة. على الرغم من وجود عناوين وعناوين فرعية وفقرات مناسبة على الصفحة، فقد تصبح الوثائق مربكة. ليست هناك طريقة للانتقال إلى قسم معيّن من الصفحة مما يزعج المستخدم المهتم بقسم معيّن. يمكن أيضًا أن تضيع المعلومات، بسبب هذا النقص في التنظيم، وتفشل في خدمة غرضها وتطلب من المستخدمين بذل جهد إضافي.
ومع ذلك، يمكن حل هذه المشاكل باتباع سلسلة من الخطوات الدقيقة. أقترح إجراء تدقيق للمحتوى كخطوة أولى في عملية إعادة التنظيم هذه. لا يساعد تدقيق المحتوى فقط في تحديد المشاكل في عرض المعلومات، بل أيضًا في إبراز أوجه القصور في المحتوى نفسه (على سبيل المثال، معلومات قديمة أو غير مكتملة). أخطط بعد ذلك لإنشاء بنية المعلومات (IA) للكشف عن شبكة المعرفة. سيتيح لنا ذلك تجميع المعلومات وفقًا لموضوعات مختلفة والعثور على روابط بين العديد من الموضوعات وثيقة الصلة. سيتم بعد ذلك استخدام الأفكار المكتسبة من خلال هاتين الممارستين لتقسيم مستندات الصفحة الواحدة إلى صفحات متعددة. يمكن بعد ذلك ربط الحزمة بأكملها والإشارة إليها في Markdown. ونتيجةً لذلك، ستتوفر نسخة منظمة بشكل أفضل من وثائق التهيئة، والتي يسهل التنقل فيها وفهمها.
الدافع على الرغم من أنني أستخدم برنامج مفتوح المصدر منذ فترة طويلة، فإن معرفتي بالمصطلح جديدة إلى حد ما، على غرار معرفتي ببرنامج Linting. عندما بدأت تعلم لغة بايثون (من خلال edX)، كنت أتساءل كيف يمكن للأخطاء الصغيرة أن تُحدث فوضى في الرمز بالكامل. ظننتُ أنّه من الرائع اختبار الرموز الخاصة بك بطريقة ما، وتحديد الأخطاء، ثم تعرّفت على مصطلح "التحليل اللغوي". لم أستخدم أي برامج بشكل ملائم حتى الآن، ولكني متأكّد من أنّها ستجعل حياتي أسهل كثيرًا في الأيام القادمة.
بفضل خلفيتي في الهندسة الكهربائية وبعض الخبرة في البرمجة، يمكنني فهم مشكلات الترميز ومتطلبات المبرمجين بطريقة أفضل. بالإضافة إلى ذلك، فإن درجة الدراسات العليا في الاتصالات الفنية والمهنية تجعلني مناصرًا للمستخدمين، في محاولة لتسهيل الحياة على الناس. ستكون مهاراتي وخبراتي كمزيج جيد لهذا المشروع، ما سيضيف قيمة إلى وثائق ESLint.
الأهداف الهدف الرئيسي لهذا المشروع هو ضمان سهولة فهم الوثائق الواردة في صفحة إعداد ESLint ولا تربك المستخدمين. من المهم لنجاح المشروع أن يكون التنقل في المحتوى سهلاً وخاليًا من جميع التعقيدات. الأهداف المهمة للمشروع هي كما يلي. - إجراء تدقيق شامل للمحتوى - إنشاء بنية المعلومات لفهم تدفق المعلومات - تحسين بنية المعلومات لإعادة تنظيم الوثائق - تحديد الروابط والمراجع بين الأقسام المختلفة للمحتوى - إعادة كتابة/تعديل أجزاء الوثائق، إذا لزم الأمر لتلبية متطلبات إعادة الضبط
- التأكد من أن المحتوى مرن وقابل لإعادة الاستخدام
وصف المشروع تكوين ESLint ميزة مهمة، ميزة تجعل ESLint قابلة للتخصيص. من المؤكد أن المستخدمين المهتمين بالتهيئة مهتمون بعنصر أو جانبين في وقت معين. وبالتالي، من المهم توجيه المستخدم إلى موضوعه الذي يهمّه، وبالتالي تزويده بالحل بطريقة فعّالة. تحتوي الحالة الحالية لوثائق تهيئة ESLint على الكثير من المعلومات المفيدة ولكنها منظمة بطريقة يمكن أن تجعل المستخدمين يشعرون بالإرهاق والإحباط والضياع. على سبيل المثال، إذا كان أحد المستخدمين مهتمًا بالاطّلاع على معلومات حول استخدام المكوّنات الإضافية التابعة لجهات خارجية في ESLint، عليه الانتقال للأسفل من خلال المناقشة حول تحديد المحلِّل والبيئات والعالم العالمي. وهذه الممارسة بأكملها تؤدي إلى إرباك المستخدمين ويمكن أن تؤدي إلى ابتعادهم عن موقع الويب. وبالمثل، إذا كان المستخدم في مكان ما في وسط الصفحة ويريد الانتقال إلى قسم معين أو لمجرد إلقاء نظرة على موضوعات مماثلة، فلن تكون مهمة سهلة بالنسبة له، حيث لا يتم تقديم مثل هذه المساعدة للمستخدمين. تحتاج هذه المشكلات إلى الاهتمام الفوري، حيث تعتمد جودة أي وثائق على مدى فائدتها، بغض النظر عن مدى صياغتها بشكل جيد. أقترح حلولاً لهذه المشكلات وغيرها من المشكلات ذات الصلة في المناقشة التالية.
تدقيق المحتوى تكون الخطوة الأولى في عملية إعادة تنظيم وثائق التهيئة هي إجراء تدقيق شامل للمحتوى. يهدف التدقيق إلى تحديد بعض المشاكل الرئيسية، مثل المحتوى القديم والمحتوى المكرّر والمحتوى غير المتوفّر وما إلى ذلك. وستتم مشاركة جدول بيانات تدقيق المحتوى الذي يتم إنشاؤه نتيجةً لذلك مع فِرق الإدارة والتوثيق للحصول على ملاحظاتهم وآرائهم. سيساعد هذا في التوصل إلى استراتيجية جديدة لهيكلة الوثائق وتقديمها.
إنشاء بنية المعلومات لفهم شبكة المعرفة أو تدفق المعلومات في وثائق الضبط، يمكن أن يكون إنشاء بنية المعلومات (IA) ذا قيمة. ستكون نتائج تدقيق المحتوى بمثابة أساس جيد لفهم وتطوير تدفق المعلومات. سيتم بعد ذلك إنشاء نسخة محسنة من بنية المعلومات لتنظيم الوثائق وتقديمها بطريقة أفضل. لن تعمل بنية المعلومات المحسّنة هذه على إعادة هيكلة المحتوى الحالي فحسب، بل ستؤدي أيضًا إلى تحديد الروابط والفروق بين الأقسام المختلفة للوثائق، مما يؤدي إلى إنشاء شبكة فعالة. على سبيل المثال، يمكن أن يتبع المحتوى في "إعداد القواعد" رابط يؤدي إلى "إيقاف القواعد باستخدام تعليقات مضمّنة". ويمكن أيضًا تحديد هذه الروابط الأخرى، ما يؤدي إلى إنشاء علاقات بين أقسام مختلفة من المستندات.
جدول المحتويات يوفر تدقيق المحتوى وبنية المعلومات المعلومات الكافية لإنشاء جدول محتويات مفصل يحتوي على روابط تؤدي إلى أقسام وأقسام فرعية محددة من الوثائق. يمكن أن يؤدي إنشاء ملفات منفصلة لكل قسم وإضافة المراجع المناسبة إلى الأقسام الأخرى إلى إضافة قيمة إلى مجموعة المستندات بالكامل. يمكن إنشاء جدول للمحتويات للمستخدمين الذين ينتقلون إلى مستندات الضبط، ما يساعدهم في رحلتهم أثناء تصفّح الموقع الإلكتروني. يمكن أن يتضمن جدول المحتويات جميع عناوين المستوى الأول والثاني لإبقائه موجزًا وشاملاً. إحدى هذه الممارسات، على سبيل المثال، هي تلك التي تستخدمها Prettier (https://prettier.io/docs/en/index.html) لتنظيم الوثائق.
سيتم إنشاء جميع الوثائق باستخدام Markdown لإبقاء الأمور بسيطة ومنظمة بشكل جيد. سيتم إيلاء عناية خاصة لضمان إمكانية إعادة استخدام المستندات، فقد تنمو وتتغير في المستقبل.
أدوات الاستخدام بعض الأدوات المهمة التي يمكن أن تكون مفيدة أثناء العمل على المشروع هي - Draw.io لإنشاء رسوم توضيحية لبنية المعلومات حسب الحاجة - Atom (أو محرر مشابه) لكتابة المستندات وتحريرها في Markdown
- GitHub لضمان التحكم في إصدار الوثائق
المعالم الرئيسية من تقديم الاقتراح إلى إكمال المشروع، ستضمن المعالم الرئيسية المؤقتة التالية اكتمال المشروع في الوقت المحدد، والحفاظ على التدفق الصحيح في العملية.
10 يوليو 2020 - 16 أغسطس 2020: مراجعة العرض واختياره سأراجع وثائق ESLint وأطوّر المهارات اللازمة لإكمال المشروع (مثل كتابة Markdown والتعاون على GitHub). سأساهم أيضًا في الوثائق عبر GitHub وسأتفاعل مع الأشخاص الآخرين للحصول على فهم أفضل للوثائق.
من 17 آب (أغسطس) 2020 إلى 13 أيلول (سبتمبر) 2020: الترابط بين أفراد المنتدى خلال فترة الترابط بين أفراد المنتدى، سأحسّن اقتراحي وفقًا للمناقشات مع المرشدين والفِرق المعنية. سأقوم أيضًا بتعديل الأهداف والمعالم الرئيسية إذا لزم الأمر. بالإضافة إلى ذلك، سأحرص على إدراج قائمة مختصرة بالأدوات التي سيتم استخدامها بعد ذلك للعمل في المشروع.
14 أيلول (سبتمبر) 2020 - 19 أيلول (سبتمبر) 2020: تدقيق المحتوى لبدء المشروع، سأجري تدقيقًا شاملاً للمحتوى لوثائق الإعدادات. سيكون الهدف هو تسليط الضوء على المشكلات المتعلقة بالمحتوى وعرضه.
في الفترة من 20 أيلول (سبتمبر) 2020 إلى 25 أيلول (سبتمبر) 2020: بنية المعلومات (IA) بعد تدقيق المحتوى، سأُنشئ بنية المعلومات لوثائق الإعدادات. سأركز على تقديم شبكة المعرفة بطريقة مفهومة. سيساعد هذا بعد ذلك في إجراء تحسينات على تدفق المعلومات.
26 سبتمبر 2020 - 30 سبتمبر 2020: الروابط والمراجع سأحلل بنية المعلومات خلال هذه المرحلة لتحديد الروابط والمراجع بين الأقسام المختلفة للوثائق. سأقوم أيضًا بإنشاء تسلسل هرمي لجميع الأقسام، مما يؤدي إلى تحسين بنية المعلومات في هذه العملية.
1 تشرين الأول (أكتوبر) 2020 - 3 تشرين الأول (أكتوبر) 2020: الخريطة النهائية بمساعدة الإحصاءات المكتسبة من خلال تدقيق المحتوى وبنية المعلومات، سأنشئ بعد ذلك خريطة نهائية لتنفيذها في وثائق الإعداد المُعاد تنظيمها. ستحتوي هذه الخريطة الشاملة على جدول محتويات، وتسلسلاً هرميًا للمواضيع، وقائمة بالروابط والمراجع المرجعية بين أقسام الوثائق.
4 أكتوبر 2020 - 05 أكتوبر 2020: مناقشة في هذه المرحلة، أي قبل تعديل الوثائق، سأقدم النتائج التي توصلت إليها وأخطط للمرشدين والفرق المعنية. ستساعد ملاحظاتهم في تحسين الخطة وإجراء التعديلات عند الضرورة.
من 6 تشرين الأول (أكتوبر) 2020 إلى 20 تشرين الأول (أكتوبر) 2020: إعادة الكتابة والتعديل في هذه الفترة، سأعدّل أقسام المستندات التي تتطلب عملاً وأعدّلها. قد تتم إعادة كتابة بعض أقسام وثائق الضبط أو قد تتم إضافة بعض العناصر الجديدة إليها. سينصب التركيز في هذه المرحلة على التأكد من أن الوثائق دقيقة ومحدثة ومرنة وقابلة لإعادة الاستخدام.
21 تشرين الأول (أكتوبر) 2020 - 25 تشرين الأول (أكتوبر) 2020: التصحيحات والروابط في هذه المرحلة، سأراجع أعمالي للتخلص من الأخطاء النحوية والهيكلية، وأراجع أيضًا أعمالي للتأكّد من دقتها. سأضيف أيضًا روابط ومراجع بين الأقسام، وفقًا لبنية المعلومات، لضمان اتباع الوثائق لخريطة المعلومات الموضوعة سابقًا.
26 أكتوبر 2020 - 31 أكتوبر 2020: النسخة النهائية للإرسال سأربط جميع ملفات Markdown، وقم بإنشاء جدول محتويات، ومشاركة المسودات مع الموجهين. سيكون هذا بمثابة إرسال المسودة الأولى في شكل حزمة كاملة.
1 تشرين الثاني (نوفمبر) 2020 - 5 تشرين الثاني (نوفمبر) 2020: أول مراجعة خلال هذه الأيام الخمسة، سأناقش المسودة الأولى مع المرشدين. سأحصل على ملاحظاتهم وأناقش أفكاري معهم لإنشاء قائمة بالتعديلات التي يجب إجراؤها.
6 تشرين الثاني (نوفمبر) 2020 - 12 تشرين الثاني (نوفمبر) 2020: التعديلات الأولى بمساعدة ملاحظات المرشدين، سأعدّل المسودة الأولى للوثائق. وستعتمد التعديلات الفعلية على طبيعة التعليقات والملاحظات، ولكن سيتم تحديد أهداف مرحلة إعادة الاستخدام والدقة والمرونة.
13 تشرين الثاني (نوفمبر) 2020 - 15 تشرين الثاني (نوفمبر) 2020: المراجعة الثانية بعد الانتهاء من التعديلات الأولية، سأناقش مستوى التقدم مع المرشدين والفرق المعنية مرة أخرى. ستركّز هذه المناقشات على التعديلات التي أُجريَت على النسخة الأولى وستسلّط الضوء أيضًا على أي مشاكل أخرى ربما تحسَّنت أثناء عملية التعديل.
16 تشرين الثاني (نوفمبر) 2020 - 19 تشرين الثاني (نوفمبر) 2020: التعديلات الثانية سأخصص بعد ذلك فترة أربعة أيام لتعديل المستند. وسيتم مناقشة الإصدارات المنتجة نتيجةً لذلك مع المرشدين من أجل إعطائهم الشكل النهائي. عند الانتهاء من هذه المرحلة، ستكون المستندات في الشكل النهائي، وستكون جاهزة للتحميل على موقع الويب ومستودع جيت هب.
من 20 تشرين الثاني (نوفمبر) 2020 إلى 23 تشرين الثاني (نوفمبر) 2020: جارٍ التحميل على الموقع الإلكتروني بعد إجراء كل التعديلات اللازمة، سيتم تحميل المستندات إلى الموقع الإلكتروني. سيتم التعامل مع أي مشاكل حدثت في هذه العملية بما أنّه لا يزال لدينا بضعة أيام للعمل على المستندات.
24 نوفمبر 2020 - 28 نوفمبر 2020: تقرير المشروع سيتم إنشاء تقرير مفصل عن المشروع في هذه الفترة التي تبلغ خمسة أيام. ستشكل الأهداف والمصاعب والمشكلات والحلول المقدمة جزءًا من تقرير المشروع. ستتم مشاركة التقرير مع الموجهين للحصول على ملاحظاتهم.
29 تشرين الثاني (نوفمبر) 2020 - 30 تشرين الثاني (نوفمبر) 2020: المشاركة النهائية سيتم إرسال المشروع مع جميع الملفات وتقرير المشروع إلى الموجّهين. سيتم إجراء مراجعة للمشروع بأكمله من خلال اجتماع/مناقشة مع المرشدين والفرق المعنية.
وطوال فترة المشروع، سأستمر في استشارة المرشدين للحصول على ملاحظاتهم القيمة. يمكن تغيير كل هذه المعالم الرئيسية بناءً على المناقشات مع الموجهين في فترات ترابط المجتمع ومراجعة الاقتراحات.
نبذة عني لدي شهادة جامعية في الهندسة الكهربائية وشهادة دراسات عليا في الاتصالات التقنية والمهنية من جامعة ولاية كارولينا الشمالية. لدي خبرة في مجالات الكتابة والتعديل التقنيين والمهنيين، وإدارة المحتوى والتواصل، ودراسات قابلية الاستخدام على الويب والأجهزة المحمولة، وتصميم التعليمات. عملتُ كمحرِّر فرعي لمنشور على الإنترنت (Global Village Space) ومتدرب في مجال الاتصالات لدى Duke Forge في جامعة ديوك. إلى جانب ذلك، لدي أيضًا اهتمام بالكتابة الإبداعية.