راهنمای سبک اسناد Bazel

با تشکر از شما برای مشارکت در مستندسازی بازل. این به عنوان یک راهنمای سبک مستندسازی سریع برای شروع شما عمل می کند. برای سؤالات سبکی که در این راهنما به آنها پاسخ داده نشده است، راهنمای سبک مستندسازی برنامه‌نویس Google را دنبال کنید.

تعریف اصول

اسناد Bazel باید این اصول را رعایت کنند:

• مختصر. تا حد امکان از کلمات کمتری استفاده کنید.
• پاک کردن از زبان ساده استفاده کنید. برای سطح خواندن کلاس پنجم بدون اصطلاحات خاص بنویسید.
• استوار. از همان کلمات یا عبارات برای مفاهیم تکراری در سراسر اسناد استفاده کنید.
• درست. با اجتناب از اطلاعات مبتنی بر زمان و وعده‌های آینده، به گونه‌ای بنویسید که محتوا تا زمانی که ممکن است درست بماند.

نوشتن

این بخش حاوی نکات اولیه نوشتن است.

سرفصل ها

• سرفصل های سطح صفحه از H2 شروع می شوند. (عنوان H1 به عنوان عنوان صفحه استفاده می شود.)

• سرصفحه ها را تا حد معقول کوتاه کنید. به این ترتیب آنها بدون بسته بندی در TOC قرار می گیرند.

  • بله : مجوزها
  • خیر : یک یادداشت کوتاه در مورد مجوزها

• از حروف جمله برای عنوان استفاده کنید

  • بله : فضای کاری خود را تنظیم کنید
  • خیر : فضای کاری خود را تنظیم کنید

• سعی کنید سرفصل ها را مبتنی بر وظیفه یا عملی کنید. اگر عنوان‌ها مفهومی هستند، ممکن است بر اساس درک باشد، اما در مورد کاری که کاربر انجام می‌دهد بنویسید.

  • بله : حفظ ترتیب نمودار
  • خیر : در مورد حفظ ترتیب نمودار

نام ها

• اسامی خاص مانند Bazel و Starlark را با حروف بزرگ بنویسید.

  • بله : در پایان ساخت، Bazel اهداف درخواستی را چاپ می کند.
  • خیر : در پایان ساخت، بازل اهداف درخواستی را چاپ می کند.

• آن را ثابت نگه دارید. برای مفاهیم موجود اسامی جدید معرفی نکنید. در صورت لزوم، از اصطلاح تعریف شده در واژه نامه استفاده کنید.

  • برای مثال، اگر در مورد صدور دستورات در ترمینال می نویسید، از ترمینال و خط فرمان در صفحه استفاده نکنید.

محدوده صفحه

• هر صفحه باید یک هدف داشته باشد و در ابتدا آن را تعریف کنید. این به خوانندگان کمک می کند تا آنچه را که نیاز دارند سریعتر پیدا کنند.

  • بله : در این صفحه نحوه نصب Bazel در ویندوز توضیح داده شده است.
  • خیر : (بدون جمله مقدماتی.)

• در پایان صفحه، به خواننده بگویید که در مرحله بعد چه کاری انجام دهد. برای صفحاتی که هیچ اقدام واضحی وجود ندارد، می‌توانید پیوندهایی به مفاهیم مشابه، مثال‌ها یا راه‌های دیگر برای کاوش اضافه کنید.

موضوع

در مستندات Bazel، مخاطبان باید در درجه اول کاربران باشند - افرادی که از Bazel برای ساختن نرم افزار خود استفاده می کنند.

• خواننده خود را «شما» خطاب کنید. (اگر به دلایلی نمی توانید از "شما" استفاده کنید، از زبانی که جنسیت خنثی است، مانند آنها استفاده کنید.)

  • بله : برای ساخت کد جاوا با استفاده از Bazel، باید یک JDK نصب کنید.
  • شاید: برای اینکه کاربران بتوانند کد جاوا را با Bazel بسازند، باید یک JDK نصب کنند.
  • خیر : برای اینکه کاربر بتواند کد جاوا را با Bazel بسازد، باید یک JDK نصب کند.

• اگر مخاطبان شما کاربران عمومی بازل نیستند، مخاطب را در ابتدای صفحه یا در قسمت تعریف کنید. سایر مخاطبان می توانند شامل نگهبانان، مشارکت کنندگان، مهاجران یا نقش های دیگر باشند.

• از "ما" دوری کنید. در اسناد کاربر هیچ نویسنده ای وجود ندارد. فقط به مردم بگویید چه چیزی ممکن است

  • بله : همانطور که Bazel تکامل می یابد، باید پایه کد خود را برای حفظ سازگاری به روز کنید.
  • خیر : Bazel در حال تکامل است و ما تغییراتی را در Bazel ایجاد خواهیم کرد که در برخی مواقع ناسازگار بوده و نیاز به تغییراتی از سوی کاربران Bazel دارد.

زمانی

در صورت امکان، از عباراتی که مسائل را در زمان مشخص می کند، مانند ارجاع به تاریخ های خاص (سه ماهه دوم 2022) یا گفتن «اکنون»، «در حال حاضر» یا «به زودی» اجتناب کنید. اینها به سرعت کهنه می شوند و اگر پیش بینی آینده باشد ممکن است نادرست باشند. در عوض، یک سطح نسخه را مشخص کنید، مانند «Bazel Xx و بالاتر از <ویژگی> پشتیبانی می‌کند» یا پیوند مشکل GitHub.

• بله : Bazel 0.10.0 یا جدیدتر از حافظه پنهان از راه دور پشتیبانی می کند.
• خیر : Bazel به زودی از حافظه پنهان از راه دور پشتیبانی می کند، احتمالاً در اکتبر 2017.

زمان فعل

• از زمان حال استفاده کنید از زمان گذشته یا آینده بپرهیزید، مگر اینکه برای وضوح کاملاً ضروری باشد.

  • بله : بازل زمانی که وابستگی هایی را پیدا می کند که با این قانون مطابقت ندارند، خطا صادر می کند.
  • خیر : اگر بازل وابستگی پیدا کند که با این قانون مطابقت ندارد، بازل خطا می دهد.

• در صورت امکان، از صدای فعال (جایی که یک سوژه بر روی یک شی عمل می کند) استفاده کنید نه از صدای غیرفعال (جایی که یک شی توسط یک سوژه عمل می کند). به طور کلی، صدای فعال جملات را واضح تر می کند زیرا نشان می دهد چه کسی مسئول است. اگر استفاده از صدای فعال باعث کاهش وضوح می شود، از صدای غیرفعال استفاده کنید.

  • بله : Bazel X را شروع می کند و از خروجی برای ساخت Y استفاده می کند.
  • خیر : X توسط Bazel آغاز می شود و سپس Y با خروجی ساخته می شود.

لحن

با لحن تجاری دوستانه بنویسید.

• از زبان محاوره ای خودداری کنید. ترجمه عباراتی که مختص انگلیسی هستند سخت تر است.

  • بله : قوانین خوب
  • نه : پس یک مجموعه قوانین خوب چیست؟

• از زبان بیش از حد رسمی خودداری کنید. طوری بنویسید که انگار دارید مفهوم را برای کسی توضیح می دهید که در مورد فناوری کنجکاو است، اما جزئیات را نمی داند.

قالب بندی

نوع فایل

برای خوانایی، خطوط را با 80 کاراکتر بپیچید. پیوندهای طولانی یا قطعه کد ممکن است طولانی تر باشند، اما باید از یک خط جدید شروع شوند. مثلا:

پیوندها

• به جای «اینجا» یا «زیر» از متن پیوند توصیفی استفاده کنید. این عمل اسکن یک سند را آسان تر می کند و برای صفحه خوان ها بهتر است.

  • بله : برای جزئیات بیشتر، به [نصب Bazel] مراجعه کنید.
  • خیر : برای جزئیات بیشتر، [اینجا] را ببینید.

• در صورت امکان جمله را با لینک پایان دهید.

  • بله : برای جزئیات بیشتر به [لینک] مراجعه کنید.
  • خیر : برای اطلاعات بیشتر به [لینک] مراجعه کنید.

لیست ها

• از یک لیست مرتب برای توضیح نحوه انجام یک کار با مراحل استفاده کنید
• از یک لیست نامرتب برای فهرست کردن چیزهایی که مبتنی بر وظیفه نیستند استفاده کنید. (هنوز باید ترتیبی از قبیل حروف الفبا، اهمیت و غیره وجود داشته باشد)
• با ساختار موازی بنویسید. مثلا:
  1. تمام آیتم های لیست را جملات بسازید.
  2. با افعالی که هم زمان هستند شروع کنید.
  3. در صورت وجود مراحلی که باید دنبال کنید، از یک لیست مرتب استفاده کنید.

متغیرهای

• از براکت های زاویه ای برای نشان دادن متغیری که کاربران باید تغییر دهند استفاده کنید. در Markdown، از براکت‌های زاویه با یک اسلش عقب فرار کنید: \<example\> .

  • بله : bazel help <command> : راهنما و گزینه های <command> چاپ می کند
  • No : bazel help command : راهنما و گزینه های "command" را چاپ می کند

• به خصوص برای نمونه کدهای پیچیده، از متغیرهایی استفاده کنید که در زمینه مفهومی دارند.

فهرست مطالب

از TOC تولید شده خودکار که توسط سایت پشتیبانی می شود استفاده کنید. یک TOC دستی اضافه نکنید.

کد

نمونه کد بهترین دوستان توسعه دهندگان هستند. احتمالاً می دانید که چگونه اینها را بنویسید، اما در اینجا چند نکته وجود دارد.

اگر به یک قطعه کد کوچک ارجاع می دهید، می توانید آن را در یک جمله جاسازی کنید. اگر می خواهید خواننده از کد استفاده کند، مانند کپی کردن یک دستور، از بلوک کد استفاده کنید.

بلوک های کد

• آن را کوتاه نگه دارید. تمام متن های اضافی یا غیر ضروری را از یک نمونه کد حذف کنید.
• در Markdown، با افزودن زبان نمونه، نوع بلوک کد را مشخص کنید.

```shell
...

• دستورات و خروجی را در بلوک های کد مختلف جدا کنید.

قالب بندی کد درون خطی

• از سبک کد برای نام فایل ها، دایرکتوری ها، مسیرها و بیت های کوچک کد استفاده کنید.
• به جای کج کردن، "نقل قول" یا پررنگ از استایل کد درون خطی استفاده کنید.
  • بله : bazel help <command> : راهنما و گزینه های <command> چاپ می کند
  • No : bazel help command : راهنما و گزینه های "command" را چاپ می کند