מדריך סגנון תיעוד של TensorFlow

שיטות עבודה מומלצות

  • התמקדו בכוונת המשתמש ובקהל היעד.
  • השתמשו במילים יומיומיות ושמרו על משפטים קצרים.
  • השתמשו בעקביות בבניית משפטים, בניסוח ובשימוש באותיות גדולות.
  • השתמש בכותרות וברשימות כדי להקל על סריקת המסמכים שלך.
  • מדריך הסגנון של מסמכי המפתחים של גוגל מועיל.

הנחה

למעט מספר יוצאים מן הכלל, TensorFlow משתמש בתחביר Markdown הדומה ל- GitHub Flavored Markdown (GFM). סעיף זה מסביר את ההבדלים בין תחביר Markdown של GFM לבין ה-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 של סמל, יש להקיף את נתיב הסמל בתוך קוים אחוריים:

נתיבים מלאים עדיפים במידה מסוימת, למעט נתיבים ארוכים. ניתן לקצר נתיבים על ידי השמטת רכיבי הנתיב המובילים. נתיבים חלקיים יומרו לקישורים אם:

  • יש לפחות . אחד בנתיב, ו
  • הנתיב החלקי הוא ייחודי בתוך הפרויקט.

נתיבי API מקושרים לכל פרויקט באמצעות API של Python שפורסם באתר tensorflow.org . ניתן בקלות לקשר למספר תת-פרויקטים מקובץ יחיד על ידי עטיפת שמות ה-API באמצעות backticks. לדוגמה:

עבור סמלים עם מספר כינויי נתיב, ישנה עדיפות קלה לנתיב התואם לדף ה-API ב- tensorflow.org . כל הכינויים יפנו לדף הנכון.

מתמטיקה ב-Markdown

ניתן להשתמש ב-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]

במחברות, הצג את התוצאה במקום להוסיף הערה (אם הביטוי האחרון בתא במחברת אינו מוקצה למשתנה, הוא מוצג אוטומטית).

במסמכי עזר של API מעדיפים להשתמש ב-doctest כדי להציג תוצאות.

טנזורים

כשמדברים על טנזור באופן כללי, אל תכתבו את המילה tensor באות גדולה. כשמדברים על אובייקט ספציפי שסופק או מוחזר מ-op, אז כדאי לכתוב את המילה Tensor באות גדולה ולהוסיף סימני ביקורת סביבה מכיוון שמדובר באובייקט 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.