الفرق بين المراجعتين لصفحة: «موسوعة حسوب:دليل المساهمين»
لا ملخص تعديل |
إضافة أقسام عن بنية صفحات الموسوعة |
||
| سطر 30: | سطر 30: | ||
* إضافة رسومات توضيحية للمفاهيم المشروحة. | * إضافة رسومات توضيحية للمفاهيم المشروحة. | ||
== بنية صفحات الموسوعة == | |||
الغرض من الموسوعة هو توفير توثيق لغات البرمجة، وليست منصةً لنشر المقالات (نستعمل [https://academy.hsoub.com أكاديمية حسوب] لهذا الغرض)، لذا انتبه إلى بنية وطريقة صياغة الصفحة. | الغرض من الموسوعة هو توفير توثيق لغات البرمجة، وليست منصةً لنشر المقالات (نستعمل [https://academy.hsoub.com أكاديمية حسوب] لهذا الغرض)، لذا انتبه إلى بنية وطريقة صياغة الصفحة. | ||
| سطر 37: | سطر 37: | ||
عند إنشائك لصفحة جديدة في توثيق لغةٍ ما، فاطلع على صفحات ذاك التوثيق لتأخذ فكرةً عن طريقة تنظيم صفحات التوثيق، وحاول قدر الإمكان أن تكون بنية الصفحة الجديدة شبيهة قدر الإمكان ببقية الصفحات. | عند إنشائك لصفحة جديدة في توثيق لغةٍ ما، فاطلع على صفحات ذاك التوثيق لتأخذ فكرةً عن طريقة تنظيم صفحات التوثيق، وحاول قدر الإمكان أن تكون بنية الصفحة الجديدة شبيهة قدر الإمكان ببقية الصفحات. | ||
=== جدول المحتويات === | |||
تولِّد البرمجية جدول المحتويات تلقائيًا، فلا حاجة إلى إنشاء جدول محتويات يدوي. يظهر جدول المحتويات قبل أول ترويسة في الصفحة، هذا يعني أنَّ الصفحة ستتألف من «مقدمة» ثم «جدول المحتويات» ثم بقية الصفحة. | |||
نرغب عادةً بجعل مقدمة الصفحة قصيرةً كي يظهر جدول المحتويات للزائر مباشرةً دون التمرير إلى الأسفل، هذا سيسمح بمعرفة محتويات الصفحة بسهولة ويُسرِّع الانتقال إلى القسم الهدف بسرعة. | |||
المنهجية التي نتبعها عادةً هي إضافة وصف قصير وبليغ عن الصفحة، مع توفير مثال إن كان المجال يسمح بذلك، مما يُذكِّر القارئ ببنية الدالة أو البنية أو الخاصية بسرعة دون الخوض في التفاصيل. | |||
=== التصنيفات === | |||
التصنيفات هي الطريقة الرئيسية لتجميع الصفحات في الموسوعة. من المهم وضع تصنيفات ذات دلالة لكل صفحة تضاف إلى توثيق إحدى اللغات أو التقنيات. | |||
اجعل أوّل تصنيف هو اسم اللغة، فأوّل تصنيف في صفحات توثيق PHP هو [[:تصنيف:PHP|PHP]]، وأوّل تصنيف في صفحات CSS هو [[:تصنيف:CSS|CSS]] (فعل ذلك سيُسهِّل الوصول إلى جميع صفحات التوثيق). أما بقية التصنيفات، فاحرص أن تبدأ باسم اللغة (كما في HTML Metadata و HTML Multimedia) لتجنب خلط صفحات الموسوعة مع بعضها. | |||
=== الهيكلية === | |||
تكون الموسوعات العامة عادةً ذات بنيةٍ مسطحة، وتُرتَّب محتوياتها باستخدام تصنيفات، أي أن تكون جميع الصفحات موجودةً في النطاق الرئيسي دون جعلها صفحاتٍ فرعيةً. وجدنا أنَّ هذا النهج ليس مناسبًا لموسوعة حسوب لوجود كثير من الصفحات ذات العناوين المشابهة. فإذا أردنا توثيق العبارة الشرطية <code>if</code> في JavaScript أو في PHP أو في Python فسنجد أنَّ النطاق الرئيسي سيصبح فوضويًا. لهذا السبب لجأنا إلى فكرة الصفحات الفرعية. | |||
اعتمدنا أن يكون لكل لغة صفحةٌ رئيسيةٌ خاصةٌ بها، والصفحات البقية التابعة لها ستكون صفحاتٍ فرعيةً. فلنأخذ توثيق HTML مثلًا على ذلك. هنالك صفحةٌ رئيسيةٌ للتوثيق باسم HTML، وتتبع جميع العناصر لتلك الصفحة، فهنالك عنصرٌ باسم [[HTML/img]] وآخر باسم [[HTML/head]]، وبهذا تجنبنا الفوضى في النطاق الرئيسي وجعلنا بنية الروابط في الموسوعة منظمةً. | |||
لاحظ أنَّ صفحة [[HTML/img]] مصنفة تحت تصنيف [[:تصنيف:HTML|HTML]] (الذي يضم جميع الصفحات التابعة لهذا التوثيق) والتصنيف [[:تصنيف:HTML Elements|HTML Elements]] (الذي يضم جميع عناصر HTML) والتصنيف [[:تصنيف:HTML Multimedia|HTML Multimedia]] (الذي يضم جميع العناصر التي تتعلق بالوسائط المتعددة في HTML). لاحظ أنَّنا لم ننشئ صفحةً فرعيةً باسم Multimedia (كما في HTML/Multimedia/img) وإنما استخدمنا تصنيفًا بهذا العنوان. | |||
أما في الحالات التي قد تتضارب فيها أسماء الدوال أو الخاصيات، كما في الخاصيات التابعة للكائنات العامة في JavaScript، فإننا نخصص صفحةً فرعيةً لكل خاصية. فعندنا الخاصية <code>toString</code> التابعة للكائن [[JavaScript/Object|Object]] وخاصية أخرى بنفس الاسم (لكن مع شرحٍ مختلف) تابعة للكائن [[JavaScript/Number|Number]] (على سبيل المثال)، فلتفادي التضارب في الأسماء، أضفنا صفحة الخاصية كصفحة فرعية لتلك الكائنات. أي [[JavaScript/Object/toString]] و [[JavaScript/Number/toString]]. لاحظ أننا لم نضف الصفحتين [[JavaScript/Object|Object]] و [[JavaScript/Number|Number]] كصفحات فرعية للصفحة Global Objects، وإنما استخدمنا ذلك كتصنيف. | |||
=== الروابط === | |||
أكثر ما يميّز الموسوعات عن أنظمة إدارة المحتوى هو الروابط الداخلية التي تسهّل التنقل بين صفحات الموسوعة. احرص على إضافة الروابط في أي مكان تجده مناسبًا. لاحظ أنَّ هنالك إمكانية إضافة روابط إلى صفحات غير موجودة، وهذا يسمح بمرونة في إضافتها، فلا حاجة إلى تعديل الصفحات القديمة عند إنشاء الصفحات الجديدة لإضافة روابط إليها. | |||
=== المصادر === | |||
من المهم أن تضع المصادر التي استقيت منها المعلومات المذكورة في الصفحة في قسمٍ بآخر كل صفحة تُضيفها. ضع كل مصدرٍ من المصادر في قائمة منقطة وأضف رابطًا خارجيًا إليه. | |||
المراجعة الحالية بتاريخ 13:01، 3 مارس 2018
توفِّر هذه الصفحة معلومات ومصادر عن تحرير وإنشاء صفحات في موسوعة حسوب.
هدف موسوعة حسوب
هدفنا الأساسي هو توفير توثيق لغات البرمجة باللغة العربية الفصيحة، بجودة عالية وبدقة كبيرة، بما في ذلك توثيق أساس اللغات ودوالها وخاصياتها كلها، مع توفير أمثلة عملية عليها يمكن للمطور الاستفادة منها.
كيف تبدأ بالمساهمة
تواصل معنا عبر البريد wiki@hsoub.com وسنتابع معك لإعطائك الصلاحيات التي تحتاج لها.
كيفية المساهمة في الموسوعة
الموسوعة هي مشروعٌ قائمٌ على مساهمة المجتمع فيها، ولا تكون المساهمة هي إنشاء الصفحات فقط، وإنما تتضمن تصحيح الأخطاء (في المعلومات، أو اللغوية)، وتحديث المحتوى، وإضافة أمثلة، وغير ذلك.
كيفية التعديل
تدعم صفحات الموسوعة نوعين من المحررات: المحرر المرئي والمحرر المصدري.
المحرر المرئي (VisualEditor) يوفِّر طريقةً سهلةً لتعديل الصفحات مرئيًا، أي أنَّه يشبه ما تستعمله في برامج التحرير المكتبي مثل Mircosoft Word أو Libreoffice Writer أو Google Docs.
المحرر المصدري يُظهِر الصفحة بصيغة wikitext التي تستعملها برمجية MediaWiki، وتمنح طريقة التعديل هذه مرونةً كبيرةً في التحرير وتعطي إمكانيات أكبر من المحرر المرئي، لكنها تعلمها أصعب من تعلم المحرر المرئي.
يمكنك الاطلاع على دليل التحرير لمزيدٍ من المعلومات.
أنواع المساهمات
- إنشاء صفحات جديدة في توثيق إحدى اللغات.
- إنشاء أقسام جديدة في صفحات موجودة مسبقًا، تشرح أمورًا لم تتطرق لها الصفحة من قبل.
- إضافة أمثلة مرتبطة بالصفحة.
- توضيح بعض الأمور التي قد يلبس فهمها على القارئ.
- إعادة صياغة الفقرات والجملة الركيكة.
- توحيد المصطلحات بين صفحات الموسوعة.
- إصلاح الأخطاء اللغوية والمطبعية.
- إضافة رسومات توضيحية للمفاهيم المشروحة.
بنية صفحات الموسوعة
الغرض من الموسوعة هو توفير توثيق لغات البرمجة، وليست منصةً لنشر المقالات (نستعمل أكاديمية حسوب لهذا الغرض)، لذا انتبه إلى بنية وطريقة صياغة الصفحة.
من المهم استقاء المعلومات التي ستضعها في الصفحة من مصادر حرة تسمح لك بإعادة نشر المحتوى، لاحظ أنَّ محتوى الموسوعة منشور تحت رخصة المشاع الإبداعي نَسب المُصنَّف -غير تجاري- الترخيص بالمثل 4.0 (CC BY-NC-SA 4.0)، لذا احرص على توافقية المحتوى معها.
عند إنشائك لصفحة جديدة في توثيق لغةٍ ما، فاطلع على صفحات ذاك التوثيق لتأخذ فكرةً عن طريقة تنظيم صفحات التوثيق، وحاول قدر الإمكان أن تكون بنية الصفحة الجديدة شبيهة قدر الإمكان ببقية الصفحات.
جدول المحتويات
تولِّد البرمجية جدول المحتويات تلقائيًا، فلا حاجة إلى إنشاء جدول محتويات يدوي. يظهر جدول المحتويات قبل أول ترويسة في الصفحة، هذا يعني أنَّ الصفحة ستتألف من «مقدمة» ثم «جدول المحتويات» ثم بقية الصفحة.
نرغب عادةً بجعل مقدمة الصفحة قصيرةً كي يظهر جدول المحتويات للزائر مباشرةً دون التمرير إلى الأسفل، هذا سيسمح بمعرفة محتويات الصفحة بسهولة ويُسرِّع الانتقال إلى القسم الهدف بسرعة.
المنهجية التي نتبعها عادةً هي إضافة وصف قصير وبليغ عن الصفحة، مع توفير مثال إن كان المجال يسمح بذلك، مما يُذكِّر القارئ ببنية الدالة أو البنية أو الخاصية بسرعة دون الخوض في التفاصيل.
التصنيفات
التصنيفات هي الطريقة الرئيسية لتجميع الصفحات في الموسوعة. من المهم وضع تصنيفات ذات دلالة لكل صفحة تضاف إلى توثيق إحدى اللغات أو التقنيات.
اجعل أوّل تصنيف هو اسم اللغة، فأوّل تصنيف في صفحات توثيق PHP هو PHP، وأوّل تصنيف في صفحات CSS هو CSS (فعل ذلك سيُسهِّل الوصول إلى جميع صفحات التوثيق). أما بقية التصنيفات، فاحرص أن تبدأ باسم اللغة (كما في HTML Metadata و HTML Multimedia) لتجنب خلط صفحات الموسوعة مع بعضها.
الهيكلية
تكون الموسوعات العامة عادةً ذات بنيةٍ مسطحة، وتُرتَّب محتوياتها باستخدام تصنيفات، أي أن تكون جميع الصفحات موجودةً في النطاق الرئيسي دون جعلها صفحاتٍ فرعيةً. وجدنا أنَّ هذا النهج ليس مناسبًا لموسوعة حسوب لوجود كثير من الصفحات ذات العناوين المشابهة. فإذا أردنا توثيق العبارة الشرطية if في JavaScript أو في PHP أو في Python فسنجد أنَّ النطاق الرئيسي سيصبح فوضويًا. لهذا السبب لجأنا إلى فكرة الصفحات الفرعية.
اعتمدنا أن يكون لكل لغة صفحةٌ رئيسيةٌ خاصةٌ بها، والصفحات البقية التابعة لها ستكون صفحاتٍ فرعيةً. فلنأخذ توثيق HTML مثلًا على ذلك. هنالك صفحةٌ رئيسيةٌ للتوثيق باسم HTML، وتتبع جميع العناصر لتلك الصفحة، فهنالك عنصرٌ باسم HTML/img وآخر باسم HTML/head، وبهذا تجنبنا الفوضى في النطاق الرئيسي وجعلنا بنية الروابط في الموسوعة منظمةً.
لاحظ أنَّ صفحة HTML/img مصنفة تحت تصنيف HTML (الذي يضم جميع الصفحات التابعة لهذا التوثيق) والتصنيف HTML Elements (الذي يضم جميع عناصر HTML) والتصنيف HTML Multimedia (الذي يضم جميع العناصر التي تتعلق بالوسائط المتعددة في HTML). لاحظ أنَّنا لم ننشئ صفحةً فرعيةً باسم Multimedia (كما في HTML/Multimedia/img) وإنما استخدمنا تصنيفًا بهذا العنوان.
أما في الحالات التي قد تتضارب فيها أسماء الدوال أو الخاصيات، كما في الخاصيات التابعة للكائنات العامة في JavaScript، فإننا نخصص صفحةً فرعيةً لكل خاصية. فعندنا الخاصية toString التابعة للكائن Object وخاصية أخرى بنفس الاسم (لكن مع شرحٍ مختلف) تابعة للكائن Number (على سبيل المثال)، فلتفادي التضارب في الأسماء، أضفنا صفحة الخاصية كصفحة فرعية لتلك الكائنات. أي JavaScript/Object/toString و JavaScript/Number/toString. لاحظ أننا لم نضف الصفحتين Object و Number كصفحات فرعية للصفحة Global Objects، وإنما استخدمنا ذلك كتصنيف.
الروابط
أكثر ما يميّز الموسوعات عن أنظمة إدارة المحتوى هو الروابط الداخلية التي تسهّل التنقل بين صفحات الموسوعة. احرص على إضافة الروابط في أي مكان تجده مناسبًا. لاحظ أنَّ هنالك إمكانية إضافة روابط إلى صفحات غير موجودة، وهذا يسمح بمرونة في إضافتها، فلا حاجة إلى تعديل الصفحات القديمة عند إنشاء الصفحات الجديدة لإضافة روابط إليها.
المصادر
من المهم أن تضع المصادر التي استقيت منها المعلومات المذكورة في الصفحة في قسمٍ بآخر كل صفحة تُضيفها. ضع كل مصدرٍ من المصادر في قائمة منقطة وأضف رابطًا خارجيًا إليه.