VOL32: Full Guide Into API Documentation
أهلًا وسهلا بكم في العدد الثاني والثلاثين من النشرة الأسبوعية لاقرأ-تِك 🎉
لا تنسوا أهلنا من صالح الدعاء,اللهم إنّا استودعناك اياهم، اللهم كُن عوناً لهم، اللهم انصرهم واحفظهم. 🇵🇸
أهلًا وسهلا بكم في العدد الثاني والثلاثين من النشرة الأسبوعية لاقرأ-تِك 🚀
سواء كنت مهندس برمجيات مبتدئ أو محترف، فنشرتنا هدفها انها تثري المحتوى التقني العربي سعيا للتطوير من جودة المحتوى باللغة العربية, من خلال تقديم أحدث المستجدات والتطورات في عالم البرمجيات، بالإضافة إلى أفضل الممارسات والنصائح القيمة, ونشر أحدث المقالات وترشيحات الكتب ومحتوى ورقة وقلم اللي بينزلوا بشكل مستمر في موقع اقرأ-تِك.
في الإصدار ده الفهرس هيكون كالآتي:
Full Guide Into API Documentation
Docker Cheatsheet
How Browser Renders Web Pages - DOM & CSSOM
Unlocking The Power of Statistics - From Data to Insights
IPFS and Decentralization
ستجدون أيضًا في هذه النشرة:
الشراكات - Sponsorship
قناة التليجرام مجانية للجميع حتى يصلك كل مقال جديد
كيفية كتابة مقالات معنا في اقرأ-تِك: والمقالات تكون متاحة ومجانية للجميع ومحفوظة باسم الكاتب بكل تأكيد
كيفية الاشتراك في اقرأ-تِك من خلال InstaPay و VodafoneCash
Full Guide Into API Documentation
الـ API documentation دليل مكتوب بيوضح وظائف الـ API، إزاي تدمجها في برنامجك، وحالات الاستخدام بتاعتها، مع شوية أمثلة. افتكر إن الـ API documentation بتكون محتوى تقني، يعني هيبقى فيها مصطلحات فنية، لكن المفروض إنها تكون سهلة القراءة والفهم.
الـ Documentation بتبقى زي الخريطة لأي مبرمج عاوز يستخدم الـ API بتاعتك. من غيرها، اللي هيجرب يشتغل بالـ API مش هيفهم أي حاجة وممكن يضيع وقت كتير يحاول يفهم بنفسه. لما يكون عندك Documentation كويسة، المطورين يقدروا يفهموا بسرعة إيه اللي لازم يتعمل، إيه اللي هيجيلهم من الـ API، وإيه اللي المفروض يبعتوه. ده بيقلل الأخطاء وبيسرع الشغل.
ليه الـ API Documentation مهمة
كمان لما الـ API Documentation تبقى مكتوبة بشكل واضح ومنظم، بتساعد إن اللي بيستخدم الـ API ميضيعش وقت كتير في الاستفسارات أو البحث عن حلول للمشاكل اللي قابلها. ده بيسهل الأمور وبيسرع عملية التطوير، وده بيزود فرصة إن ناس أكتر تستخدم الـ API بتاعتك، وده طبعًا في مصلحتك كمطور أو شركة.
مين المفروض يكتب API Documentation؟
الـ APIs بيطورها مبرمجين البرمجيات. وبما إنهم هما اللي بيبنوها وبيستخدموها، بيكون أسهل لهم إنهم يكتبوا الوثائق بتاعتها. لكن المشكلة إن المبرمجين ساعات بيكتبوا الوثائق بشكل فني بحت، وده بيخلي الوثائق صعبة الفهم على ناس كتير. وكمان ممكن ياخد منهم وقت طويل عشان يطوروا الـ API ويكتبوا الوثائق في نفس الوقت.
عشان كده الحل الأفضل إن اللي يكتب الوثائق يكون Technical Writer. الـ Technical Writer هو شخص بيجمع بين مهارات الكتابة التقنية والمعرفة التقنية عشان ينتج وثائق تكون مفهومة وسهلة.
الـ Technical Writer بيتعلم عن الـ API من المطورين، وبعدين بيكتب دروس وأمثلة تشرح استخدام الـ API. المطورين بعد كده بيتابعوا الكاتب عشان يتأكدوا إن الوثائق صحيحة وبيزودوه بأي معلومات إضافية لو احتاج.
الهدف النهائي إن الكل يشتغل سوا عشان يطلع وثائق بتشرح الـ API بشكل واضح وتساعد المستخدمين من غير لخبطه.
محتويات الـ API Documentation
محتويات الـ API Documentation بتكون متقسمة لأجزاء أساسية، وكل جزء بيشرح نقطة معينة بتساعد المبرمجين يفهموا إزاي يستخدموا الـ API بشكل صحيح. تعالوا نشوف أهم الحاجات اللي بتكون موجودة
Docker Cheatsheet
جمعنالك أهم الأوامر اللي ممكن تحتاجها في شغلك اليومي بdocker في مكان واحد وبالعربي عشان نوفر مجهود الترجمة ل اللغة الأم اللي طول النهار بنعمله دا 😅
الأوامر متقسمة ل ٣ فئات:
الـ Docker Images Commands: أوامر خاصة بالتعامل مع ال docker images و هي دي ورقة المواصفات اللي بنبني علي أساسها ال containers بتاعتنا.
الـ Docker Containers Commands: أوامر خاصة بالتعامل مع ال docker containers ودي بتبقي عبارة عن التطبيق بتاعك مع البيئة الكاملة اللي محتاجها عشان يشتغل
الـ General Commands: أوامر عامة و أوامر للتعامل مع Docker Hub وهو ال Repository الأساسي اللي كل الناس بتنشر عليه ال Docker Images الخاصة بتطبيقاتها ويقدر بقية المطورين ينزلوا منه ال Images و ينشأوا منها Containers ويستخدموها.
الشراكات - Sponsorship
بفضل الله أصبح متاح حاليا دعمنا من خلال الرعاة والشراكات وفعلنا الـ Sponsorship وتقدروا تشوفوا التفاصيل كاملة من هنا والـ Analytics بتاعتنا من خلال اقرأ-تِك والنشرة الأسبوعية 🚀
لا تدع شيء يفوتك!
بفضل الله قمنا بإطلاق قناة اقرأ-تِك على التليجرام مجانًا للجميع 🚀
آملين بده اننا نفتح باب تاني لتحقيق رؤيتنا نحو إثراء المحتوى التقني باللغة العربية ، ومساعدة لكل متابعينا في انهم يوصلوا لجميع أخبار اقرأ-تِك من حيث المقالات ومحتوى ورقة وقلم والنشرة الأسبوعية وكل جديد بطريقة سريعة وسهلة
مستنينكوا تنورونا , وده رابط القناة 👇
How Browser Renders Web Pages - DOM & CSSOM
لو سألت نفسك إزاي المتصفح بيقدر يعرض صفحة ويب كاملة قدامك بعد ما تضغط على لينك؟ الموضوع دا بيعدي بكذا خطوة مهمة، وكل خطوة ليها شغل مختلف وبتأثر بشكل مباشر على سرعة تحميل الصفحة وتجربة المستخدم.
بناء شجرتين DOM و CSSOM
عشان المتصفح يقدر يعرض (يـ render) الصفحة، أول حاجة بيعملها إنه يبني شجرتين شجرة الـ DOM وشجرة الـ CSSOM.
الـ "DOM "Document Object Model: دي شجرة بتمثل كل عنصر HTML في الصفحة.
الـ "CSSOM "CSS Object Model: دي شجرة بتمثل الـ styles اللي بتحدد شكل الصفحة (الـ CSS).
المتصفح محتاج يبني الشجرتين دول عشان يعرف إزاي هيتعامل مع كل عنصر في الصفحة وأشكاله من الـ CSS.
ليه بناء الشجرتين دول مهم؟
الـ DOM بيحدد المحتوى اللي هيظهر، والـ CSSOM بيحدد شكله، وبالتالي المتصفح لازم يعرف التنسيق النهائي لكل عنصر في الصفحة قبل ما يرسمه (يـ render). بعد ما المتصفح يبني الشجرتين دول، بيبدأ يجمعهم في خطوة مهمة اسمها "شجرة العرض" (render tree)، ودي اللي بتربط المحتوى بالتصميم وتخلي المتصفح يقدر يرسم العناصر بالشكل المطلوب.
رحلة الـ HTML والـ CSS لحد ما تبقى صفحة مرئية من الـ Bytes للشاشة
البيانات (Bytes) بتتحول لحروف (characters) → رموز (tokens) → عقد (nodes) → وفي الآخر بتتحول لـ object model.
الـ HTML Markup بيتحول لـ Document Object Model" DOM"، والـ CSS Markup بيتحول لـ CSS Object Model" CSSOM".
الـ DOM و CSSOM هما Data Structures مستقلين عن بعض.
في Chrome DevTools، تقدر تستخدم Performance Panel عشان تـ Capture وتـ Inspect الـ Costs لبناء ومعالجة الـ DOM والـ CSSOM.
كل خطوة ليها تكلفة معينة، والهدف إننا نقلل التكلفة دي بقدر الإمكان عشان الصفحة تشتغل بأسرع وقت! ⚡
إزاي المتصفح بيحوّل الـ HTML الخام اللي جاي من الشبكة أو الهارد لحاجة يقدر يعرضها على الشاشة؟ العملية دي بتعدي في كذا مرحلة، كل مرحلة لها شغل معين، تعالوا نفهمهم مع بعض.
الـ (DOM) Document Object Model
لو عندك Document Object Model" DOM" زي دا:
Unlocking The Power of Statistics - From Data to Insights
علم الإحصاء هو البوابة لفهم البيانات الكبيرة واستخدامها فيما بعد في الذكاء الاصطناعي. بينقسم إلى نوعين؛ الإحصاء الوصفية اللي بتبسط الداتا والإحصاء الاستدلالية اللي بتضع فرضيات معينة وتختبر صحتها فيما بعد.
بعد ما البيانات بتتجمع من مصادر عشوائية ومختلفة بيصعب التعامل معاها حتى بعد ما تعدى بمراحل ال Cleaning والمراحل المبدأية لفهمها، دا له سببين:
إن البيانات غامضة جدًا فبنعمل تحليل استكشافي ليها (EDA) واللي بيعتمد بشكل كامل على الأساليب الإحصائية وقوانينها.
إن البيانات تكون كبيرة وفي تزايد مستمر ولحظي زي بيانات السكان مثلًا؛ عدم توافرها كلها بيصعّب علينا تجميعها ورصدها.. ودا بنحله بأخذ عينة عشوائية صغيرة وإيجاد العلاقة بينها وبين البيانات الكبيرة والمتزايدة دي.
البيانات من وجهة نظر الإحصاء
الإحصاء بشكل عام بتتعامل مع البيانات الرقمية، عشان كدا في البداية مهم نحدد نوع البيانات المستخدمة وفهمها كويس لتحديد الأساليب الاحصائية المناسبة للتعامل معاها..
البيانات بتنقسم إلى نوعين:
البيانات النوعية (Qualitative Data): هي بيانات وصفية لا تحتوى على أرقام، مثل التقدير الدراسي، نوع المهنة.. وهنا الإحصاء بتستخدم التوزيعات التكرارية (Frequency Distribution) لتوضيح عدد مرات تكرار كل قيمة وصفية في البيانات.
من تطبيقاتها العملية: تحليل استطلاعات الرأي المعتمدة على تصنيفات محددة زي رأي العملاء في خدمة معينة سواء بالإيجاب أو بالسلب.
البيانات الكمية (Quantitative Data): ودي بيانات بتحتوي على أرقام وقيم عددية وبتنقسم لنوعين:
بيانات نقدر نحصرها في أرقام معينة زي عدد الأشخاص أو عدد السيارات مثلًا ودي اسمها البيانات المتقطعة (Discrete Data).
تاني نوع هو البيانات المستمرة (Continuous Data) وهي بيانات بنعبر عنها بمجموعة أرقام ولكن في نطاق من القيم ، زي مستويات درجات الحرارة والفئات العمرية والوزن.
النوع دا من البيانات بنستخدم معاه أساليب إحصائية زي ال mode وال median وال standard deviation هيتم مناقشتها فيما بعد.
من تطبيقاتها العملية: تحليل أسعار المنتجات واستهلاك العملاء ليها والتنبؤ باحتياجنا لمنتج معين بكثرة في المستقبل بمساعدة قوانين الإحتمالات (Probabilties).
نتيجة لاختلاف أنواع البيانات؛ ظهرت بالتبعية أنواع كتيرة من التحليلات اللي بتعتمد بشكل أساسي على علم الإحصاء عشان تناسب الاختلافات دي.
IPFS and Decentralization
مؤخرا انتشرت مصطلحات جديدة مثل اللامركزية Decentralization و الجيل الثالث من شبكات الويب Web3 فما هو مفهوم اللامركزية وما هي اهم البروتوكولات الخاصه بها؟
اللامركزية - Decentralization
اللامركزية Decentralization هي عكس المركزية Centralization ففي الوضع الافتراضي تقوم الشركة برفع بياناتها على سيرفر مركزي Centralized Server سواء كانت تملكه او تقوم باستئجاره من احد مزودين الخدمات السحابية Cloud Services Providers ولكن بالنسبة للاعتماد على سيرفر مركزي كلي تكون البيانات عرضة اكبر للخطر.
فاذا تم التلاعب بالبيانات يصعب اكتشاف التلاعب كما انه اذا انقطعت الخدمة وانقطع الاتصال بالسيرفر المركزي فاننا لن نملك الوصول للبيانات ، وهذا بخلاف ان الشركات التي تملك السيرفرات هي من تملك البيانات بشكل كامل حيث يمكنها بيع البيانات والتحكم فيها بحذف ما لا يروق لها كما هو الحال مع بعض مواقع التواصل الاجتماعي!
ومن هنا تاتي اللامركزية لتوفر لنا نظام يكون فيه المستخدم هو المالك الفعلي للبيانات وتكون البيانات متاحة ومشفرة على اكثر من عٌقدة Node بحيث اذا تم التلاعب في عٌقدة فإنه يتم تصحيحها بمعلومية الباقي كما انه اذا توقفت عٌقدة عن العمل فان الباقي يوفرون البيانات للمستخدم.
واحد اهم البروتوكولات اللامركزية هو IPFS ويقابله HTTP في الانظمة المركزية
Arabic Language & Artificial Intelligence
البوست تم نشره على صفحة م.أبو بكر والكلام مقتبس منه مساهمة في دعم اللغة العربية في مجال الذكاء الاصطناعي
واحدة من اكبر معوقات تقدم اللغة العربية في مجال الذكاء الاصطناعي , هو ندرة المصادر العربية الموثوقة لتدريب أو تقييم نماذج اللغة ، والأمر ده بجد, فيه تقصير كبير, لو قارنا الجهد المبذول من لغات عدد متحدثيها أقل من العربية بمراحل.
طب انت ليك دور؟ كشخص عادي جداً, حابب يكون لك نصيب في التقدم ده.
بالطبع انت عارف ان ممكن لو بذلك دقائق من وقتك, يكون ليك بصمة كبيرة في المجال ده؟
تنقيح البيانات من الامور المفتقدة كثيراً في عالمنا العربي ، بمعني انه يكون فيه متحدثين للعربية, يراجعوا بيانات قبل بدء استخدامها. أمر يتطلب تطوع اكبر عدد لضمان أفضل نتيجة.
البيانات اللي انت حتنقحها دي حيتم تقييم بيها نماذج الذكاء الاصطناعي. و بذلك, نضمن أكبر درجة من توافق النتائج بين النماذج و البشر.
البيانات دي في النهاية, ستكون مفتوحة المصدر, و غير مخصصة للأغراض التجارية. و ستدعم الباحثين في عملهم.
مجموعة 2A2I حالياً بتعد بيانات اختبار مهمة. البيانات حتختبر قدرة النموذج اللغوي انه يستطيع استخلاص الاجابة لســؤال من ضمن عدد من الفقرات النصية.
المطلوب منك, انك تساهم و تراجع البيانات دي في دقائق. ⏳
و هناك جوائز لأكبر 💐 3 مساهمين في تنقيح البيانات.
كيـــف تساهم؟ 😉
الفكرة ببساطة, حتدخل اللنك ده
https://bit.ly/airage-oall
و تسجل عضوية على Huggingface عشان يتفتحلك لوحة التحكم
حتلاقي أمامك بيانات على هيئة
- ⏺ سؤال
- ⏺ اجابة مقترحة من نموذج ذكاء اصطناعي
- ⏺ عدد من الفقرات تم عرضها على النموذج لإستخلاص الاجابة
و انت لديك القدرة على تعديل الاجابة (اذا كانت تحتاج تعديل), و الضغط ✅ Submit . او رفض السؤال بالكامل ❌ Discard
بس لازم تخلي بالك من كام حاجة 😉 . لان دورك كبشري هنا مهم
- 🔴 السؤال نفسه ممكن يكون مش قوي لغوياً. و ده متركزش فيه, طالما هو نفسه مفهوم
- 🔴الفقرات النصية تم استخلاصها من كتب حقيقية.
- 🔴الاجابة لازم تكون معتمدة على واحد أو اكثر من المصادر (الفقرات), لكن حتى لو الاجابة صحيحة (من وجهة نظرك), لكن ملهاش اي مصدر بالفعل من الفقرات. لازم تعدل الاجابة و تكتب (لا توجد اجابة).
- 🔴لو لقيت ان السؤال مثلا بيسأل عن أمر غريب, كما انه يسأل عن (صورة) او (مصدر) غير موجود أصلاً, ممكن ترفض السؤال Discard
- 🔴الاجابات المقترحة كلها مولدة بإستخدام نماذج ذكاء اصطناعي. لو وجدت اجابة صحيحة, لكن غير سليمة لغوياً (ده أمهم مهم جداً), او ناقصة. قم بتعديلها فوراً. 😉
- 🔴 ليس شرط انه تكون الاجابة معتمدة على فقرة واحدة. ممكن أكثر من فقرة تساهم في تكوين الاجابة. المهم اننا نضمن ان النموذج دائماً بيعتمد على فقرة أو اكثر لتوليد اجابته, و لا يعتمد على ذاكرته الخاصة 🎃 , او يتحدث خارج السياق, او يغير في المعلومات الواردة (كأنه يغير من اسم شخص او يغير رقم).
يا ريت الناس تساهم في نشر البوست ده 😊 , لأن كثير من المهتمين باللغة العربية, لو كل واحد قضى عشر دقائق من وقته. ممكن ننجز المهمة. ⚡
نصائح مهمة
كن حريص على السلامة اللغوية للاجابات
حاول التركيز على مدى تطابق الاجابات مع ورودها في النصوص.
ارفض اي نماذج الأسئلة فيها غير منطقية بالمرة. او غير مفهومة ليك كانسان.
تقدروا دلوقتي تشتركوا في اقرأ-تِك بخصم الـ 20% وتنضموا لمجتمع مهتم بالقراءة في هندسة البرمجيات بـ 50 جنيه بس 🎉
وتستمتعوا بحرية كاملة في قراءة المقالات في مواضيع مختلفة بجودة عالية زي:
Data Structure & Algorithms , System Design , Distributed Systems , Micro-Services, Clean Code, Refactoring, Databases , Web Development, DevOps وغيرهم كتير باللغة العربية!
بالاضافة لمحتوى ورقة وقلم اللي بنشرح فيه مفاهيم برمجية بطريقة سهلة وباستعمال صور توضيحية 🚀
ولو فيه مشاكل في الدفع الأونلاين فمتاح دلوقتي الاشتراك من خلال InstaPay و VodafoneCash 💪
تقدروا تتواصلوا معانا من خلال الـ WhatsApp Business أو من خلال الرسايل على مواقع التواصل الاجتماعي أو من خلال البريد الالكتروني contact@eqraatech.com 😍
رؤيتنا هي إثراء المحتوى التقني العربي وجعل التعلم من خلال القراءة أمتع، وذلك من خلال إثراء المحتوى التقني باللغة العربية وتشجيع المبرمجين على القراءة بلغتهم الأم والتفكير أيضًا بها.
لذلك اتحنا الفرصة أمام الجميع للمساهمة ومساعدتنا في نشر واثراء المحتوى التقني باللغة العربية, من خلال كتابة المقالات التقنية في مختلف مجالات هندسة البرمجيات.
وجب التنويه أنه لن يتم نشر كافة الأعمال التي تصل إلينا، وإنما سيتم الانتقاء منها ما يحقق هدفنا بإثراء المحتوى التقني العربي، ولذلك قد تُطلب بعض التعديلات من الكاتب قبل النشر.
لمعرفة المزيد بخصوص :
💬 المعايير العامة لكتابة ونشر المقالات
⚡️ كيفية الإرسال
🔥 التزامات اقرأ-تِك تجاه الكتاب
يمكنكم قراءة كافة التفاصيل من هنا 👇
