دليل أنماط مستندات Bazel

نشكرك على المساهمة في مستندات Bazel. يوفّر لك هذا الدليل دليلاً سريعًا للوثائق لمساعدتك على البدء. بالنسبة إلى أي أسئلة حول النمط لم تتم الإجابة عنها من خلال هذا الدليل، اتّبع دليل نمط مستندات مطوّري برامج Google.

تعريف المبادئ

يجب أن تدعم مستندات Bazel هذه المبادئ:

• موجز. وننصحك باستخدام أقل عدد ممكن من الكلمات.
• محو. استخدِم لغة بسيطة. اكتب بدون استخدام لغة مفهومة لقراءة القراءة من المستوى الخامس.
• الاتساق. استخدم الكلمات أو العبارات نفسها للمفاهيم المكررة خلال المستندات.
• صحيح. لا بدّ من كتابة المحتوى بطريقة صحيحة قدر الإمكان من خلال تجنّب تقديم معلومات أو وعود مستقبلية.

الكتابة

يحتوي هذا القسم على نصائح أساسية للكتابة.

الرؤوس

• تبدأ العناوين على مستوى الصفحة من المستوى الثاني. (يتم استخدام العناوين H1 كعناوين للصفحة.)

• اجعل العناوين قصيرة بقدر الإمكان. وبهذه الطريقة، تتناسب مع بنود الخدمة بدون الالتفاف.

  • نعم: الأذونات
  • لا: ملاحظة موجزة عن الأذونات

• استخدام حالة أحرف الجملة في العناوين

  • نعم: إعداد مساحة العمل
  • لا: إعداد Google Workspace

• حاول أن تكون العناوين مستندة إلى المهام أو قابلة للتنفيذ. إذا كانت العناوين تصورية، قد تستند إلى الفهم، ولكن تكتب إلى ما يفعله المستخدم.

  • نعم: حفظ ترتيب الرسم البياني
  • لا: عند الحفاظ على ترتيب الرسم البياني

الاسماء

• كتابة الأسماء الصحيحة بالأحرف الكبيرة، مثل Bazel وStarlark

  • نعم: في نهاية الإصدار، يطبع "بازيل" الأهداف المطلوبة.
  • لا: في نهاية الإصدار، يطبع البازيل الأهداف المطلوبة.

• الحفاظ على الاتّساق لا تُدخِل أسماءً جديدة للمفاهيم الحالية. حيثما ينطبق ذلك، استخدم المصطلح المُحدّد في مسرد المصطلحات.

  • على سبيل المثال، إذا كنت تكتب عن إصدار الأوامر على محطة طرفية، لا تستخدم كل من الوحدة الطرفية وسطر الأوامر في الصفحة.

نطاق الصفحات

• يجب أن يكون لكل صفحة غرض واحد ويجب تحديده في البداية. وهذا يساعد القرّاء في العثور على ما يحتاجون إليه بشكلٍ أسرع.

  • نعم: تغطي هذه الصفحة كيفية تثبيت Bazel على نظام التشغيل Windows.
  • لا: (ليس هناك أي جملة تمهيدية.)

• في نهاية الصفحة، أخبر القارئ بما يجب عليه فعله بعد ذلك. بالنسبة إلى الصفحات التي لا يتوفر فيها إجراء واضح، يمكنك تضمين روابط لمفاهيم أو أمثلة مماثلة أو طرق أخرى للاستكشاف.

Subject

في مستندات Bazel، يجب أن يكون الجمهور في الأساس من المستخدمين، وهم الأشخاص الذين يستخدمون Bazel لإنشاء برامجهم.

• تحديد القارئ باسمك (إذا كنت لا يمكنك استخدام "أنت" لسبب ما، استخدِم لغة محايدة للجنسين، مثلها.)

  • نعم: لإنشاء رمز جافا باستخدام Bazel، يجب تثبيت ملف JDK.
  • ربما: يحتاج المستخدمون إلى تثبيت رمز JDK حتى يتمكّنوا من إنشاء رمز جافا باستخدام Bazel.
  • لا: لكي يتمكّن المستخدم من إنشاء رمز جافا باستخدام Bazel، عليه تثبيت JDK.

• إذا لم يكن جمهورك من مستخدمي Bazel العامين، عرِّف الجمهور في بداية الصفحة أو في القسم. ويمكن أن تتضمن شرائح الجمهور الأخرى المعنيين أو المساهمين أو المهاجرين أو أدوارًا أخرى.

• تجنَّبنا "نحن". في مستندات المستخدم، ليس هناك مؤلف أعلِم الناس بما هو ممكن.

  • نعم: مع تطوُّر Bazel، عليك تعديل قاعدة الرموز البرمجية للحفاظ على التوافق.
  • لا: يتطوّر Bazel حاليًا وسيتمّ إجراء تغييرات على Bazel تكون غير متوافقة في بعض الأحيان وتتطلب بعض التغييرات من مستخدمي Bazel.

زماني

وعند الإمكان، تجنَّب العبارات التي توجّه الأمور في الوقت، مثل الإشارة إلى تواريخ محدّدة (الربع الثاني من عام 2022) أو قول "الآن" أو "حاليًا" أو "قريبًا". قد تصبح هذه المعلومات قديمة وقد لا تكون صحيحة إذا كان العرض متوقّعًا في المستقبل. بدلاً من ذلك، حدِّد مستوى إصدار بدلاً من ذلك، مثل "Bazel Xx والإصدارات الأحدث يدعم <feature> أو رابط مشكلة GitHub.

• نعم: يتوافق Bazel 0.10.0 أو الإصدارات الأحدث منه مع التخزين المؤقت عن بُعد.
• لا: سيتوافق Bazel قريبًا مع التخزين المؤقت عن بُعد، وذلك على الأرجح في تشرين الأول (أكتوبر) 2017.

توتر

• استخدِم التوتر الحالي. تجنَّب التوتر في المستقبل أو المستقبل ما لم يكن ضروريًا تمامًا للتوضيح.

  • نعم: يُصدِر Bazel خطأً عندما يعثر على تبعيات لا تتوافق مع هذه القاعدة.
  • لا: إذا وجد Bazel تبعية لا تتوافق مع هذه القاعدة، سيصدر خطأ.

• حيثما أمكن، استخدِم صوتًا نشطًا (حيث يعمل شخص معيّن على كائن معيّن) وليس صوتًا خاملاً (حيث يعمل كائن معيّن على الهدف). بوجهٍ عام، يجعل استخدام الصوت النشط الجُمل أكثر وضوحًا لأنه يوضح من هو المسؤول. في حال كانت هناك استخدام سلبي للصوت ينتقد الصوت، استخدِم الصوت السلبي.

  • نعم: يبدأ Bazel X ويستخدِم الإخراج لإنشاء Y.
  • لا: يبدأ X بازل ثم يتم إنشاء Y بعد ذلك مع الإخراج.

الأسلوب

اكتب بنغمة تناسب النشاط التجاري.

• تجنَّب اللغة العامية. من الصعب ترجمة العبارات الخاصة باللغة الإنجليزية.

  • نعم: قواعد جيدة
  • لا: ما هي مجموعة القواعد الجيدة؟

• ويجب تجنّب اللغة الرسمية بشكل مفرط. اكتفِ بالوصف كما لو كنت تشرح المفهوم للأشخاص المهتمين بالتكنولوجيا، ولكنهم لا يعرفون التفاصيل.

التنسيق

نوع الملف

لسهولة القراءة، يتم التفاف الأسطر على 80 حرفًا. الروابط الطويلة أو مقتطفات الرمز قد تكون أطول، ولكن يجب أن تبدأ في سطر جديد. مثال:

الروابط

• استخدم نص رابط وصفيًا بدلاً من "هنا" أو "أدناه". وتُسهّل هذه الممارسة عملية مسح مستند ضوئيًا، كما أنها أفضل لبرامج قراءة الشاشة.

  • نعم: لمزيد من التفاصيل، يُرجى الاطِّلاع على [تثبيت البازيل].
  • لا: لمزيد من التفاصيل، اطّلِع على [هنا].

• أنهِ الجملة التي تضم الرابط، إن أمكن.

  • نعم: لمزيد من التفاصيل، راجع [link].
  • لا: يُرجى الاطّلاع على [الرابط] للحصول على مزيد من المعلومات.

القوائم

• استخدام قائمة مرتَّبة لوصف كيفية إنجاز مهمة باستخدام الخطوات
• يمكنك استخدام قائمة غير مرتَّبة لإدراج العناصر التي لا تستند إلى المهمة. (يجب أن يكون الترتيب مختلفًا، مثل الترتيب الأبجدي والأهمية وما إلى ذلك)
• اكتب ببنية متوازية. مثلاً:
  1. اجعل كل جمل عناصر القائمة.
  2. ابدأ باستخدام الأفعال التي لها نفس الإجهاد.
  3. استخدِم قائمة مرتبة إذا كانت هناك خطوات يجب اتّباعها.

العناصر النائبة

• استخدِم الأقواس المثلثة للإشارة إلى متغيّر يجب على المستخدمين تغييره. يمكنك استخدام أشرطة مائلة إلى وضع أقواس معقوفة بجانب \<example\>.

  • نعم: bazel help <command>: مساعدة مطبوعات وخيارات <command>
  • لا: مساعدة bazel الأمر: مساعدة الصور المطبوعة وخيارات "الأمر"

• بالنسبة إلى نماذج الرموز المعقدة خاصة، يمكنك استخدام العناصر النائبة المفيدة في السياق.

جدول المحتوى

استخدِم بنود الخدمة التي يتم إنشاؤها تلقائيًا والمتوافقة مع الموقع الإلكتروني. لا تضِف بنود خدمة يدوية.

الرمز

نماذج الرموز هي أفضل الأصدقاء لمطوّري البرامج. قد تكون على دراية بكيفية كتابة هذه المقالة، إليك بعض النصائح.

إذا كنت تشير إلى مقتطف صغير من الرمز، يمكنك تضمينه في جملة. إذا كنت تريد من القارئ استخدام الرمز، مثل نسخ أمر، استخدِم كتلة رموز.

مجموعات رموز

• احرص على أن يكون المقطع الدعائي قصيرًا. أزِل كل النصوص المكرّرة أو غير الضرورية من نموذج الرمز.
• في Markdown، حدّد نوع كتلة الرموز عن طريق إضافة لغة النموذج.

```shell
...

• فصل الأوامر وإخراجها في شكل رموز مختلفة.

تنسيق الرمز المضمّن

• استخدم نمط الرمز لأسماء الملفات، والأدلة، والمسارات، وأجزاء صغيرة من الشفرة.
• استخدام نمط الرمز المضمّن بدلاً منمائل ،"أو علامات الاقتباس"، أوغامق.
  • نعم: bazel help <command>: مساعدة مطبوعات وخيارات <command>
  • لا: مساعدة bazel الأمر: مساعدة الصور المطبوعة وخيارات "الأمر"