أفضل الممارسات
- ركز على نية المستخدم والجمهور المستهدف.
- استخدم كلمات شائعة الاستخدام واجعل الجمل قصيرة.
- استخدم بنية جملة متسقة، وصياغة متسقة، واستخداماً متسقاً للأحرف الكبيرة.
- استخدم العناوين والقوائم لتسهيل تصفح مستنداتك.
- يُعد دليل أسلوب مستندات مطوري جوجل مفيدًا.
تخفيض السعر
باستثناءات قليلة، يستخدم TensorFlow صيغة Markdown مشابهة لصيغة GitHub Flavored Markdown (GFM). يشرح هذا القسم الاختلافات بين صيغة GFM Markdown وصيغة Markdown المستخدمة في توثيق TensorFlow.
اكتب عن البرمجة
إشارات ضمنية إلى التعليمات البرمجية
ضع `backticks` حول الرموز التالية عند استخدامها في النص:
- أسماء الوسائط:
`input`،`x`،`tensor` - أسماء الموترات المُعادة:
`output`،`idx`،`out` - أنواع البيانات:
`int32`،`float`،`uint8` - أسماء العمليات الأخرى المشار إليها في النص:
`list_diff()`،`shuffle()` - أسماء الفئات:
`tf.Tensor`،`Strategy` - اسم الملف:
`image_ops.py`،`/path_to_dir/file_name` - التعبيرات أو الشروط الرياضية:
`-1-input.dims() <= dim <= input.dims()`
كتل التعليمات البرمجية
استخدم ثلاث علامات اقتباس معكوسة لفتح وإغلاق كتلة التعليمات البرمجية. يمكنك اختيارياً تحديد لغة البرمجة بعد مجموعة علامات الاقتباس المعكوسة الأولى، على سبيل المثال:
```python
# some python code here
```
الروابط في لغة ماركداون ودفاتر الملاحظات
الروابط بين الملفات في المستودع
استخدم روابط نسبية بين الملفات في مستودع GitHub واحد. قم بتضمين امتداد الملف.
على سبيل المثال، هذا الملف الذي تقرأه موجود في مستودع https://github.com/tensorflow/docs . لذلك، يمكنه استخدام المسارات النسبية للربط بملفات أخرى في نفس المستودع كما يلي:
-
[Basics](../../guide/basics.ipynb)ينتج Basics .
هذا هو الأسلوب المُفضّل لأنه بهذه الطريقة تعمل جميع الروابط على مواقع tensorflow.org و GitHub و Colab . كما يبقى القارئ في نفس الموقع عند النقر على أي رابط.
روابط خارجية
بالنسبة للروابط إلى الملفات غير الموجودة في المستودع الحالي، استخدم روابط Markdown القياسية مع عنوان URI الكامل. يُفضّل الربط بعنوان URI الخاص بموقع tensorflow.org إن كان متاحًا.
للربط بشفرة المصدر، استخدم رابطًا يبدأ بـ https://www.github.com/tensorflow/tensorflow/blob/master/ ، متبوعًا باسم الملف بدءًا من جذر GitHub.
عند الربط من موقع tensorflow.org ، قم بتضمين `` في رابط Markdown بحيث يظهر رمز "الرابط الخارجي".
-
[GitHub](https://github.com/tensorflow/docs)يُنتج GitHub
لا تقم بتضمين معلمات استعلام URI في الرابط:
- استخدم الرابط التالي:
https://www.tensorflow.org/guide/data - ملاحظة:
https://www.tensorflow.org/guide/data?hl=en
صور
النصائح الواردة في القسم السابق تخص الروابط المؤدية إلى الصفحات. أما الصور فتُعالج بشكل مختلف.
بشكل عام، لا ينبغي عليك إيداع الصور، بل عليك إضافة فريق TensorFlow-Docs إلى طلب السحب الخاص بك، وطلب استضافة الصور على موقع tensorflow.org . هذا يساعد في تقليل حجم مستودعك.
إذا قمتَ بتحميل صور إلى مستودعك، فلاحظ أن بعض الأنظمة لا تدعم المسارات النسبية للصور. يُفضّل استخدام عنوان URL كامل يُشير إلى الموقع النهائي للصورة على موقع tensorflow.org .
روابط إلى وثائق واجهة برمجة التطبيقات (API)
يتم تحويل روابط واجهة برمجة التطبيقات (API) عند نشر الموقع. للربط بصفحة مرجع واجهة برمجة التطبيقات الخاصة برمز ما، ضع مسار الرمز بين علامتي اقتباس معكوسة (``).
- ينتج
`tf.data.Dataset`tf.data.Dataset
يُفضّل استخدام المسارات الكاملة، باستثناء المسارات الطويلة. يمكن اختصار المسارات بحذف أجزائها الأولى. سيتم تحويل المسارات الجزئية إلى روابط في الحالات التالية:
- يوجد على الأقل نقطة
.في المسار، و - المسار الجزئي فريد من نوعه داخل المشروع.
يتم ربط مسارات واجهة برمجة التطبيقات (API) لكل مشروع يحتوي على واجهة برمجة تطبيقات بايثون منشورة على موقع tensorflow.org . يمكنك بسهولة الربط بمشاريع فرعية متعددة من ملف واحد عن طريق وضع أسماء واجهة برمجة التطبيقات بين علامتي اقتباس معكوسة (`). على سبيل المثال:
- ينتج عن
`tf.metrics`و`tf_agents.metrics`و`text.metrics`ما يلي:tf.metricsوtf_agents.metricsوtext.metrics.
بالنسبة للرموز التي لها عدة مسارات بديلة، يُفضّل المسار الذي يطابق صفحة واجهة برمجة التطبيقات (API) على موقع tensorflow.org . وسيتم إعادة توجيه جميع المسارات البديلة إلى الصفحة الصحيحة.
الرياضيات في لغة ماركداون
يمكنك استخدام MathJax داخل TensorFlow عند تحرير ملفات Markdown، ولكن لاحظ ما يلي:
- يتم عرض MathJax بشكل صحيح على موقع tensorflow.org .
- لا يتم عرض MathJax بشكل صحيح على GitHub.
- قد يكون هذا الترميز منفراً للمطورين غير الملمين به.
- لضمان الاتساق، يتبع موقع tensorflow.org نفس قواعد Jupyter/Colab.
استخدم $$ حول كتلة من MathJax:
$$
E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2
$$\[ E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2 \]
قم بتغليف تعبيرات MathJax المضمنة بـ $ ... $ :
This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $
هذا مثال على تعبير MathJax مضمن: \( 2 \times 2 = 4 \)
تعمل الفواصل \\( ... \\) أيضًا مع العمليات الحسابية المضمنة، ولكن شكل $ يكون أحيانًا أكثر قابلية للقراءة.
أسلوب نثري
إذا كنت ستكتب أو تعدل أجزاء كبيرة من الوثائق السردية، فيرجى قراءة دليل أسلوب توثيق مطوري جوجل .
مبادئ الأناقة الجيدة
- راجع الإملاء والقواعد في مساهماتك. تتضمن معظم برامج التحرير مدققًا إملائيًا أو توفر إضافةً للتدقيق الإملائي. يمكنك أيضًا لصق النص في مستند جوجل أو أي برنامج آخر للمستندات لإجراء تدقيق إملائي وقواعدي أكثر دقة.
- استخدم أسلوبًا وديًا وبسيطًا. اكتب وثائق TensorFlow بأسلوب حواري، كما لو كنت تتحدث إلى شخص آخر وجهًا لوجه. استخدم نبرة داعمة في المقال.
- تجنّب التنويهات والآراء والأحكام القيمية. كلمات مثل "بسهولة" و"ببساطة" و"بكل بساطة" تحمل في طياتها افتراضات. قد يبدو لك أمر ما سهلاً، ولكنه قد يكون صعباً على شخص آخر. حاول تجنّب هذه الكلمات قدر الإمكان.
- استخدم جملًا بسيطة ومباشرة، وتجنّب المصطلحات المعقدة. فالجمل المركبة، وسلاسل الجمل، والعبارات الاصطلاحية الخاصة بكل مكان، قد تجعل النص صعب الفهم والترجمة. إذا أمكن تقسيم الجملة إلى جزأين، فمن الأفضل فعل ذلك. تجنّب استخدام الفواصل المنقوطة. استخدم القوائم النقطية عند الحاجة.
- قدّم سياقًا. لا تستخدم الاختصارات دون شرحها. لا تذكر مشاريع أخرى غير TensorFlow دون إرفاق روابط لها. اشرح سبب كتابة الكود بهذه الطريقة.
دليل الاستخدام
عمليات
في ملفات Markdown، استخدم # ⇒ بدلاً من علامة المساواة المفردة عندما تريد إظهار ما تُرجعه العملية.
# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0) # ⇒ [1, 2, 3, 5]
في دفاتر الملاحظات، اعرض النتيجة بدلاً من إضافة تعليق (إذا لم يتم تعيين التعبير الأخير في خلية دفتر الملاحظات لمتغير، فسيتم عرضه تلقائيًا).
في وثائق مرجع واجهة برمجة التطبيقات، يُفضل استخدام doctest لعرض النتائج.
الموترات
عند الحديث عن الموتر بشكل عام، لا تكتب كلمة "موتر" بحرف كبير. أما عند الحديث عن الكائن المحدد الذي يتم تقديمه إلى عملية أو إرجاعه منها، فيجب كتابة كلمة "موتر" بحرف كبير ووضع علامات اقتباس معكوسة حولها لأنك تتحدث عن كائن Tensor .
لا تستخدم كلمة "الموترات " (بصيغة الجمع) لوصف عدة كائنات Tensor إلا إذا كنت تتحدث فعلاً عن كائن واحد Tensors . بدلاً من ذلك، قل "قائمة (أو مجموعة) من كائنات Tensor ".
استخدم كلمة "الشكل" لتوضيح محاور الموتر، واعرض الشكل بين قوسين مربعين مع علامات اقتباس معكوسة. على سبيل المثال:
If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.
كما ذُكر أعلاه، يُفضّل استخدام مصطلحي "المحور" أو "الفهرس" بدلاً من "البُعد" عند الحديث عن عناصر شكل Tensor . وإلا فمن السهل الخلط بين "البُعد" وبُعد الفضاء المتجهي. المتجه ثلاثي الأبعاد له محور واحد طوله 3.