راهنمای سبک نگارش
این راهنمای سبک نگارش، به شما کمک می‌کند مخاطب واژه‌نامه، ساختار تعریف، سطح جزئیات موردنیاز و چگونگی حفظ سبک یکسان را درک کنید.
واژه‌نامه Cloud Native از راهنمای سبک نگارش پیش‌فرض مخزن CNCF پیروی می‌کند. علاوه بر آن، قوانین زیر را دنبال می‌کند:
- از زبان ساده و قابل‌دسترس استفاده کنید و از اصطلاحات فنی پیچیده و Buzzwordها بپرهیزید.
- از زبان محاوره‌ای پرهیز کنید
- از زبان صریح و ملموس استفاده کنید
- انقباض‌ها (contraction) را حذف کنید
- از حالت مجهول به‌ندرت استفاده کنید
- جمله‌ها را به شکل مثبت بیان کنید
- علامت تعجب بیرون از نقل‌قول‌ها استفاده نشود
- اغراق نکنید
- از تکرار بپرهیزید
- مختصر باشید
مخاطب
واژه‌نامه برای مخاطب فنی و غیر فنی نوشته می‌شود. تعاریف را با زبان ساده توضیح دهید و فرض نکنید مخاطب دانش فنی دارد. توضیحات بیشتر در بخش تعریف و راهنمای سبک نگارش زبان اشاره آمده است.
حداقل تعریف قابل ارائه
هدف ما این است که درک اصطلاحات Cloud Native برای همه آسان باشد؛ بنابراین روی سادگی تمرکز می‌کنیم. از زبان شفاف و ساده همراه با مثال‌هایی استفاده کنید که هر کاربر فناوری بتواند با آن ارتباط بگیرد، در حالی که یک حداقل تعریف قابل ارائه را دست‌کم از منظر فنی تأمین می‌کنید. نمی‌خواهیم از زمینه و مثال‌ها صرف‌نظر کنیم—این موارد به خواننده کمک می‌کند مفهوم را بفهمد—اما اگر جزئیات فنی برای درک لازم نیست، آن را حذف می‌کنیم. هدف این است که موضوع بیش از حد پیچیده نشود. وقتی خواننده ایده اصلی را درک کرد، منابع دیگر کمک می‌کنند عمیق‌تر شود و این فراتر از دامنه این واژه‌نامه است.
قالب تعریف
هر اصطلاح واژه‌نامه در یک فایل Markdown ذخیره می‌شود و این قالب را دنبال می‌کند:
---
title:
status:
category:
---
A quick summary of the technology or concept.
## Problem it addresses
A few lines about the problem it's addressing.
## How it helps
A few lines on how the thing solves the problem.
Title
برچسب title همیشه در بالای Layout تعریف قرار می‌گیرد و مقدار آن باید به صورت Title Case باشد.
---
title: Definition Template
Status
برچسب status بعد از title می‌آید. این برچسب میزان کار باقی‌مانده برای تکمیل تعریف را نشان می‌دهد.
مقادیر مجاز:
- Completed
- Feedback Appreciated
- Not Started
همیشه می‌توانید برای تعریف کامل‌شده Issue باز کنید. زمانی که تعریفی در حال تغییر است، وضعیت آن به Feedback Appreciated تغییر می‌کند. توجه داشته باشید که نباید مقادیر وضعیت را بومی‌سازی کنیم.
---
title: Definition Template
status: Feedback Appreciated
Tags
برچسب tags بعد از status می‌آید. برای اینکه Tagها معنا‌دار و مفید باشند، آن‌ها را با دقت استفاده می‌کنیم. استفاده بیش از حد تنها معنا را کم‌رنگ می‌کند. استثنا fundamental است که نشان می‌دهد این اصطلاح برای درک سایر مفاهیم Cloud Native ضروری است؛ اغلب اصطلاحات فقط یک Tag خواهند داشت.
نکته: تنها در صورتی Tag جدید معرفی کنید که Maintainerها تأیید کرده باشند. هنگام افزودن Tag به ورودی، مطمئن شوید دقیقاً مطابق فهرست زیر (تک‌واژه، بدون غلط املایی) نوشته شده‌اند.
Tagهای فعلی:
- application
- architecture
- fundamental
- infrastructure
- methodology
- networking
- property
- security
---
title: Definition Template
status: Feedback Appreciated
tags: ["tag 1", "tag 2", ""]
---
Definition
دو زیرعنوان
تعاریف دسته‌های technology و concept شامل خلاصه‌ای سریع و دو زیرعنوان هستند:
- (خلاصه سریع) نمای کلی کوتاه و واضح از موضوع موردبحث ارائه دهید.
- Problem it addresses: روی مسئله تمرکز کنید، نه راه‌حل (که در بخش بعد می‌آید). از ذکر اصطلاحی که تعریف می‌شود خودداری کنید. مسئله توضیح می‌دهد «چه چیزی» ما را به سمت نیاز به آن مفهوم برد.
- How it helps: حالا به اصطلاح برگردید. چگونه به مسئله شرح‌داده‌شده پاسخ می‌دهد؟
توجه داشته باشید که Propertyها به بخش‌های جداگانه نیاز ندارند؛ یک تعریف کافی است.
لطفاً برای سهولت بررسی از Semantic Line Break استفاده کنید.
کیفیت حرف اول را می‌زند
اگر ورودی شما Merge شود، تا زمانی که شخص دیگری آن را بهبود دهد، تعریف رسمی CNCF خواهد بود. ایجاد تعریفی که با استانداردهای بالای CNCF هم‌خوان باشد شتاب‌بردار نیست—کیفیت زمان و تلاش می‌خواهد.
تحقیق کنید: حتی اگر مطمئن هستید اصطلاح را می‌شناسید، بررسی کنید که درست متوجه شده‌اید. ما اغلب در سازمان خود اصطلاحات را به شکلی استفاده می‌کنیم که ممکن است تصویر کامل را منعکس نکند. هنگام تحقیق، به‌ویژه زمانی که ۱۰۰٪ با اصطلاح آشنا نیستید، از منابع متعدد استفاده کنید. بسیاری از تعاریف یک‌طرفه هستند، به‌خصوص اگر توسط Vendor ارائه شده باشند. واژه‌نامه باید تعاریف Vendor-Neutral و پذیرفته‌شده جهانی ارائه دهد.
کپی نکنید. قوانین واژه‌نامه مانند هر انتشار جدی دیگری است. کار دیگران را کپی و پیست نکنید مگر اینکه نقل‌قول کنید و به آن‌ها نسبت دهید. اگر بخشی را دوست دارید، آن را با کلمات خود بازنویسی کنید.
به منابع معتبر استناد کنید. هرجا ممکن بود به منابع معتبر مانند مستندات پروژه لینک بدهید. توجه کنید که نمی‌توانیم به محتوایی که Vendorها تولید کرده‌اند لینک بدهیم.
ساده نگه دارید
هدف واژه‌نامه توضیح مفاهیم پیچیده با کلمات ساده است—کاری surprisingly دشوار که احتمالاً چندین بازنگری می‌طلبد. هنگام نگارش تعریف همیشه مخاطب را در نظر داشته باشید. از اصطلاحات صنعت و Buzzwordها بپرهیزید—ممکن است متوجه شوید دوباره به سراغشان می‌روید و لازم باشد خود را تمرین دهید دنبال واژه‌های دیگری بگردید.
در صورت امکان از مثال‌های دنیای واقعی استفاده کنید تا خوانندگان (به‌ویژه غیر فنی‌ها) بهتر بفهمند چه زمانی و چرا ایده‌ای که توضیح می‌دهید مرتبط است.
هنگامی که در تعریف خود از اصطلاحات موجود واژه‌نامه استفاده می‌کنید، همیشه به آن‌ها لینک دهید (فقط اولین اشاره باید لینک داشته باشد).
مثال: خلاصه تعریف Service Mesh را ببینید. به تعاریف Microservice، Service، Reliability و Observability لینک می‌دهد. علاوه بر آن، مثال دنیای واقعی ارائه می‌کند که چالش‌های شبکه در محیط Microservice (چیزی که برای افراد غیر فنی ملموس نیست) را با مشکلات Wi-Fi (چیزی که هر کاربر لپ‌تاپ می‌شناسد) مقایسه می‌کند. هرجا می‌توانید چنین ارتباطی برقرار کنید.
با سند Google یا Word شروع کنید
پیشنهاد می‌کنیم با یک سند Google یا Word شروع کنید، چند روز آن را کنار بگذارید و سپس دوباره مرور کنید. این کار کمک می‌کند جمله‌هایی را پیدا کنید که می‌توانند ساده‌تر و قابل‌دسترس‌تر بیان شوند. همچنین قبل از ارسال PR حتماً از Spellcheck استفاده کنید.
برای اینکه هنگام کار روی یک اصطلاح، شخص دیگری PR ارسال نکند، Issue را Claim کنید (یا بسازید) و درخواست کنید به شما اختصاص داده شود. اطلاعات بیشتر در سند How To Contribute آمده است.
پیش از شروع، چند تعریف منتشرشده واژه‌نامه را بخوانید تا سطح جزئیات و دشواری و زمان مناسب برای آوردن مثال را احساس کنید.
راهنمای سبک نگارش ویدیو زبان اشاره
اگر در حال مشارکت یک ویدیوی زبان اشاره هستید، لطفاً این دستورالعمل‌ها را دنبال کنید تا ویدیوها واضح، آموزنده و برای مخاطب گسترده (از جمله افراد شنوا) قابل دسترس باشند.
تجهیزات فنی
تنها به یک دوربین با وضوح بالا و یک پایه نیاز دارید. یک گوشی هوشمند مدرن کافی است.
تنظیمات ضبط
نورپردازی: نور از روبه‌رو باشد تا چهره و دستان شما به‌خوبی روشن شود.
پس‌زمینه: مقابل پس‌زمینه‌ای یکنواخت و ساده فیلم‌برداری کنید تا نشانه‌های حواس‌پرت‌کننده از حرکات اشاره دور باشند. مطمئن شوید دکورهای مزاحم دیده نمی‌شوند.
لباس: لباسی ساده با رنگ یکنواخت (بدون طرح) بپوشید که با رنگ پوستتان کنتراست داشته باشد.
جایگاه دوربین: مطمئن شوید از سر تا آرنج در قاب دیده می‌شود و دوربین هم‌سطح چشم قرار دارد. دوربین باید عمود بر پس‌زمینه باشد تا تصویر زاویه‌دار به نظر نرسد.
فضای اشاره: تا حد امکان فضا را طوری انتخاب کنید که هنگام نشستن یا ایستادن، فضای کامل اشاره در اختیار داشته باشید.
صدا: در صورت امکان میکروفون (صدای ورودی) را بی‌صدا کنید تا نویز ناخواسته ضبط نشود.
اشاره کردن
وضوح و دقت: هر علامت را دوبار از روبه‌رو ضبط کنید و آن‌قدر آهسته اشاره کنید که افراد غیر آشنا به زبان اشاره هم بتوانند آن را ببینند و تقلید کنند. نمایش علامت از زاویه جانبی ضروری نیست مگر آن‌که به وضوح بیشتر کمک کند.
حالت چهره: از حالات چهره آرام یا خنثی استفاده کنید. لب‌خوانی یا شکلک‌های اغراق‌آمیز قویاً توصیه نمی‌شود. تا حد امکان تماس چشمی با دوربین داشته باشید.
تکرار: برای هر ویدیو تنها یک بار اشاره لازم است، چون می‌توان پخش را Loop کرد. تکرار علامت در ویدیو ضروری نیست.
مدت‌زمان: طول کل ویدیو نباید از ۷ ثانیه بیشتر شود.
حروف‌دستی (Fingerspelling): تا حد امکان از زبان اشاره برای واژه استفاده کنید. Fingerspelling آخرین گزینه است و معمولاً برای واژه‌های کوتاه یا مخفف به‌کار می‌رود.
وضعیت بدن: هنگام اشاره روبه‌رو بایستید یا بنشینید و نگاهتان به دوربین باشد. نشان دادن علامت از زاویه جانبی لازم نیست. هنگام استراحت، دست‌ها باید پایین و رها باشند.
نکته‌ها
صرفه‌جویی در فضا: هرچه ویدیو کوتاه‌تر باشد، حجم فایل کمتر و آپلود سریع‌تر است.
اشتباه اشکال ندارد: هنگام ضبط، دوربین را خاموش نکنید و چند بار تلاش کنید. احتمال بیشتری وجود دارد میان تلاش‌ها کلیپ مناسب پیدا کنید و می‌توانید بخش‌های ناخواسته را برش دهید. این کار از ضبط‌های متعدد با یک تلاش در هر ویدیو کارآمدتر است.
نمونه ویدیو: برای نمونه‌ها به فهرست پخش CNCF Glossary: Cloud Native Signs مراجعه کنید.
پس‌تولید
ویرایش: در صورت نیاز آغاز و پایان ویدیو را برش بزنید.
برچسب‌گذاری: حداقل در نام فایل ویدیو، پیش از بارگذاری باید اصطلاح واژه‌نامه مربوط به آن اشاره درج شود؛ مانند kubernetes.mp4.
صدا: در صورت امکان، ترک صوتی را به‌طور کامل حذف کنید.
آپلود: ویدیو را در کانال Slack با نام #glossary-sign-language به اشتراک بگذارید و بازخورد بخواهید. در صورت تأیید، مسئولان Sign Language واژه‌نامه به شما کمک می‌کنند ویدیو را در فهرست پخش CNCF بارگذاری کنید. لطفاً ویدیو را در کانال شخصی YouTube خود بارگذاری نکنید، زیرا با توجه به اینکه CNCF برای انتشار نهایی از YouTube استفاده می‌کند، YouTube ممکن است ویدیوهای تکراری را از همه حساب‌ها حذف کند (برای جلوگیری از سوءاستفاده کسب درآمد).
بارگذاری در فهرست CNCF: ویدیو را در کانال Slack با نام #glossary-sign-language به اشتراک بگذارید و بازخورد بخواهید. در صورت تأیید، مسئولان Sign Language واژه‌نامه به شما کمک می‌کنند ویدیو را در فهرست پخش CNCF قرار دهید.
فرایند بازبینی: چه انتظاری داشته باشید
توجه داشته باشید که در حال حاضر تعداد کمی Maintainer داریم که این کار را در زمان آزاد خود انجام می‌دهند. گاهی می‌توانیم تعاریف را سریع بررسی کنیم و گاهی کمی طول می‌کشد—از شکیبایی شما سپاس‌گزاریم. اگر پرسشی دارید، در کانال Slack با نام #glossary با ما تماس بگیرید (برای یافتن کانال و چگونگی دسترسی، به سند How To Contribute مراجعه کنید).
هدف ما این است که واژه‌نامه بهترین منبع ممکن باشد. پس از ارسال PR ممکن است از شما بخواهیم یک یا چند بازنگری انجام دهید. دلسرد نشوید—این موضوع برای بسیاری از PRها پیش می‌آید. این رفت‌وبرگشت‌ها و همکاری ما تضمین می‌کند که مشارکت شما به تعریفی مفید تبدیل شود که خوانندگان سراسر جهان به آن رجوع می‌کنند.