מדריך הסגנון של מסמכי בזל

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

הגדרת העקרונות

המסמכים ב-Bazel צריכים לעמוד בעקרונות הבאים:

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

כתיבה

סעיף זה מכיל טיפים בסיסיים לכתיבה.

כותרות

• כותרות ברמת הדף מתחילות ב-H2. (כותרות H1 משמשות ככותרות דפים).

• הכותרות צריכות להיות קצרות והגיוניות. כך ניתן להתאים אותם ל'תנאים והגבלות' ללא עטיפה.

  • כן: הרשאות
  • לא: הערה קצרה על הרשאות

• יש להשתמש באותיות רישיות בכותרות

  • כן: הגדרה של סביבת העבודה
  • לא: הגדרה של סביבת העבודה

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

  • כן: שמירה של סדר התרשימים
  • לא: שמירה על סדר התרשימים

שמות

• יש להשתמש בשמות עצם תקינים, כמו Bazel ו-Starlark.

  • כן: בסוף ה-build, Bazel מדפיסה את היעדים המבוקשים.
  • לא: בסוף ה-build, bazel מדפיס את היעדים המבוקשים.

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

  • לדוגמה, אם אתם כותבים על הפקת פקודות במסוף, אל תשתמשו גם במסוף וגם בשורת הפקודה בדף.

היקף הדף

• לכל דף צריכה להיות מטרה אחת ויש להגדירה בהתחלה. זה עוזר לקוראים למצוא את מה שהם צריכים מהר יותר.

  • כן: הדף הזה מסביר איך להתקין את Bazel ב-Windows.
  • לא: (ללא משפט היכרות).

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

Subject

בתיעוד של Bazel, הקהל צריך להיות בעיקר משתמשים - האנשים שמשתמשים ב-Bazel לבניית התוכנה שלהם.

• פונים לקוראים כאל "את/ה". (אם מסיבה כלשהי אינכם יכולים להשתמש במילה "אתם", השתמשו בשפה נייטרלית, כגון זו).

  • כן: כדי לבנות קוד Java באמצעות Bazel, צריך להתקין JDK.
  • אולי: כדי שמשתמשים יוכלו לבנות קוד Java עם Bazel, הם צריכים להתקין JDK.
  • לא: כדי שמשתמש יוכל לבנות קוד Java עם Bazel, עליו להתקין JDK.

• אם הקהל שלך אינו משתמש כללי ב-Bazel, הגדר את הקהל בתחילת הדף או בקטע הזה. קהלים אחרים יכולים לכלול מנחים, תורמים, נודדים או תפקידים אחרים.

• הימנעו מ "אנחנו". במסמכים של משתמשים אין מחבר; פשוט לספר לאנשים מה אפשר להיות.

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

זמני

במידת האפשר, יש להימנע מהצגת מונחים שמכוונים דברים בזמן, כמו למשל הפניה לתאריכים ספציפיים (רבעון 2 2022) או אמירת "עכשיו", "כרגע" או "בקרוב". פרק הזמן הזה מסתיים במהירות, וייתכן שהוא שגוי אם זה תחזית עתידית. במקום זאת, יש לציין רמת גרסה, כמו "Bazel Xx ואילך תומך ב-<feature> או בקישור לבעיה של GitHub.

• כן: Bazel 0.10.0 ואילך תומך בשמירה במטמון מרחוק.
• לא: בקרוב פלטפורמת Bazel תתמוך במטמון מרחוק, ככל הנראה באוקטובר 2017.

מוזיקה מותחת

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

  • כן: Bazel מפיקה שגיאה כאשר היא מוצאת יחסי תלות שאינם תואמים לכלל זה.
  • לא: אם Bazel תזהה תלות שאינה תואמת לכלל הזה, Bazel תנפיק שגיאה.

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

  • כן: Bazel מתחילה את X ומשתמשת בפלט כדי לבנות את Y.
  • לא: X מתחילה ביוזמת Bazel ואז אחרי Y היא תיבנה עם הפלט.

טון

מומלץ לכתוב בטון ידידותי לעסקים.

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

  • כן: כללים טובים
  • לא: אז מה זה כלל טוב?

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

עיצוב

סוג קובץ

כדי שהטקסט יהיה קריא, יש לעטוף שורות באורך של 80 תווים. קישורים ארוכים או קטעי קוד עשויים להיות ארוכים יותר, אך צריכים להתחיל בשורה חדשה. למשל:

קישורים

• צריך להשתמש בטקסט קישור תיאורי במקום "כאן" או "למטה". תרגול זה מקל על סריקת מסמך ומתאים יותר לקוראי מסך.

  • כן: לפרטים נוספים, ראה [התקנת Bazel].
  • לא: פרטים נוספים זמינים [כאן].

• סיים את המשפט עם הקישור, אם אפשר.

  • כן: פרטים נוספים זמינים בקישור [link].
  • לא: מידע נוסף זמין בכתובת [link].

רשימות

• יש להשתמש ברשימה מסודרת כדי לתאר איך לבצע משימה באמצעות שלבים
• השתמש ברשימה לא ממוינת כדי לפרט דברים שאינם מבוססים על משימה. (עדיין אמור להיות סדר מיון, כגון סדר אלפביתי, חשיבות וכו')
• כתיבה במבנה מקביל. לדוגמה:
  1. מגדירים את כל המשפטים של הפריטים ברשימה.
  2. התחילו עם פועל זהה לאותו זמן.
  3. אם מדובר בצעדים שיש לבצע, יש להשתמש ברשימה ממוינת.

Placeholders

• משתמשים בסוגריים זוויתיים כדי לציין משתנה שהמשתמשים צריכים לשנות. ב-Markup, יציאה מסוגריים זוויתיים עם קו נטוי הפוך: \<example\>.

  • כן: bazel help <command>: הדפסות עזרה ואפשרויות עבור <command>
  • לא: עזרה של bazel

• בעיקר עבור דגימות קוד מורכבות, השתמשו ב-placeholders שמתאימים להקשר.

תוכן עניינים

שימוש בתנאים ובהגבלות שנוצרו באופן אוטומטי על ידי האתר. אין להוסיף תנאים והגבלות ידניים.

קוד

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

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

חסימות קוד

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

```shell
...

• הפרדה של פקודות ופלט לבלוקים שונים של קוד.

עיצוב קוד בתוך שורה

• מומלץ להשתמש בסגנון קוד לשמות קבצים, לספריות, לנתיבים ולקטעי קוד קטנים.
• יש להשתמש בסגנון קוד מוטבע במקום בנטוי, ב"מירכאות" או בהדגשה.
  • כן: bazel help <command>: הדפסות עזרה ואפשרויות עבור <command>
  • לא: עזרה של bazel