راهنمای سبک
این سند دستورالعملهایی را که هنگام نوشتن مستندات استفاده میکنیم، مشخص میکند.
سبک نگارش
وضوح و اختصار را هدف قرار دهید
نامهای کوتاهتر مینوشتم، اما وقت نداشتم.
وقت و توجه خوانندگان محدود است. به آن احترام بگذارید.
همین امر برای ارتباطات خطاب به مشارکتکنندگان و نگهدارندگان نیز صدق میکند: این یک پروژه عمومی است و افراد زیادی نوشتههای شما را خواهند خواند. از این اهرم با احتیاط استفاده کنید.
از دستورالعملهای زبان ساده مبتنی بر شواهد پیروی کنید.
از اصطلاحات تخصصی (ژارگن) استفاده نکنید. ممکن است خوانندگان با اصطلاحات فنی خاصی آشنا نباشند.
اگر کلمات کوتاهتر و سادهتری وجود دارند که همان معنا را میرسانند، از کلمات طولانی و پیچیده استفاده نکنید.
هنگام ارائه دستورالعملها از لحن امری (دستوری) استفاده کنید. برای مثال، بنویسید:
بسته
python310را بهbuildInputsاضافه کنید.از لحن محاورهای استفاده نکنید، زیرا تمرکز را از محتوا منحرف میکند. برای مثال، ننویسید:
از این به بعد، بیایید همانطور که در آموزش قبلی دیدیم، بسته
python310را بهbuildInputsاضافه کنیم.
از زبان فراگیر استفاده کنید
برگرفته از پیماننامه مشارکتکنندگان و آییننامه رفتار کارپنتریز:
- از زبان خوشآمدگویی و فراگیر استفاده همدلی و احترام نشان دهید
- نسبت به سایر افراد همدلی و احترام نشان دهید
- به دیدگاهها و تجربیات مختلف احترام بگذارید
- انتقاد سازنده را بپذیرید و با بزرگواری ارائه دهید
- روی آنچه به نفع جامعه است تمرکز کنید
از اصطلاحات عامیانه و ضربالمثلها خودداری کنید، زیرا درک آنها برای کسانی که زبان مادریشان انگلیسی نیست دشوار باشد.
تلاش نکنید بامزه باشید. شوخطبعی به شدت وابسته به فرهنگ است. در بهترین حالت، لطیفهها ممکن است دستورالعملهای مربوطه را مبهم کنند. در بدترین حالت، لطیفهها ممکن است خوانندگان را آزرده خاطر سازند و تلاشهای ما برای کمک به یادگیری آنها را بیاعتبار کنند.
از ارجاعات به فرهنگ عامه استفاده نکنید. آنچه ممکن است از نظر شما شناختهشده باشد، ممکن است برای افرادی با پسزمینههای مختلف کاملاً نامفهوم و حواسپرتکن باشد.
لحن
موضوع را به صورت واقعبینانه توصیف کنید و در دستورالعملهای مستقیم از لحن امری استفاده کنید.
رابطه شخصی با خوانندگان را فرض نگیرید، وضوح و اختصار را بر توسل به احساسات ترجیح دهید.
از کلمه «شما» برای اشاره به خواننده استفاده کنید و تنها از «ما» برای اشاره به نویسندگان استفاده کنید. هر دو باید به ندرت نیاز شوند.
برای مثال:
شما باید اسرار را روی ماشین راه دور مستقر کنید. ما ترجیح دادیم فرآیند صریح و دستی را با استفاده از
scpدر اینجا نشان دهیم، اما ابزارهای مختلفی برای خودکارسازی آن وجود دارد.
درست بنویسید، به منابع استناد کنید
تنها چیزی که از عدم وجود مستندات بدتر است، مستندات نادرست است. یک راه برای اطمینان از درستی، استناد به منابع است. اگر ادعایی درباره نحوه کارکرد چیزی مطرح میکنید (مثلاً اینکه یک آرگومان خط فرمان وجود دارد)، به مستندات رسمی آن موضوع پیوند دهید. ما مایلیم شبکهای از مستندات را حفظ کنیم، بنابراین پیوند دادن به سایر مستندات به تقویت بومسازگان مستندات کمک میکند.
بهطور صریح تشویق میشود که در صورت لزوم، راهنماها را بهروزرسانی یا بازساختاردهی کنید تا تجربه کلی بهبود یابد.
نشانهگذاری و کد منبع
نمونههای کد
همیشه قبل از نشان دادن کد، با توصیف کلامی هدف آن یا کاری که انجام خواهد داد، انگیزهای برای آن ایجاد کنید.
ضد مثال
Run this command: ```bash :(){'{'} :|:& {'}'};: ```
مثالهای غیربدیهی ممکن است به توضیح اضافی نیاز داشته باشند، بهویژه اگر از مفاهیمی خارج از زمینه دادهشده استفاده کنند. برای توضیحاتی که ممکن است تمرکز جریان خواندن را به هم بزنند، از یک جعبه محتوای جمعشونده استفاده کنید.
مثال
Set off a [fork bomb](https://en.wikipedia.org/wiki/Fork_bomb): ```bash :(){'{'} :|:& {'}'};: ``` **Detailed explanation** This Bash command defines and executes a function `:` that recursively spawns copies of itself, quickly consuming system resources. ``` همیشه کد را در خود متن توضیح دهید. از کامنتها در نمونهکدها بسیار کم و با احتیاط استفاده کنید، مثلاً برای برجسته کردن یک جنبهی خاص. خوانندگان هنگام جستجوی اطلاعات تمایل دارند نگاهی اجمالی به حجم زیادی از کد بیندازند، حتی اگر بیشتر آن کامنت باشد. بهویژه مبتدیان احتمالاً خواندن کدهای پیچیدهبهنظررسنده را طاقتفرسا میدانند و به همین دلیل ممکن است کلاً از آن دوری کنند. اگر به نظر میرسد یک نمونهکد به توضیح درونخطی زیادی نیاز دارد، جایگزین کردن آن با یک نمونه سادهتر را در نظر بگیرید. اگر این کار امکانپذیر نیست، مثال را به چند بخش تقسیم کنید، آنها را بهطور جداگانه توضیح دهید و سپس نتیجهی ترکیبی را در انتها نشان دهید. نمونهکدهایی که _قصد_ بر کارکردنشان است، باید کار کنند. اگر میخواهید مثالی را ارائه دهید که کار نمیکند (مثلاً دارید یک اشتباه رایج را به تصویر میکشید)، این موضوع را از قبل توضیح دهید. بسیاری از خوانندگان بدون اینکه جلوتر را بخوانند تا بفهمند کد قرار نیست کار کند، در تلاش برای وادار کردن کد نمونه به کار کردن، دچار مشکل میشوند. نمونهکدها در صورت امکان باید شامل یک زبان برنامهنویسی باشند تا هنگام رندر شدن، برجستهسازی نحوی (syntax highlighting) روی آنها اعمال شود، مثلاً: ``` ```python print("Hello, World!") ``` ```### سرتیترها بزرگترین سرتیتر (`#`) را برای عنوان رزرو کنید. برای تقسیمبندی محتوا در بدنه سند، از سرتیترهای Markdown از `##` تا `###` استفاده کنید. سرتیترهای با دانهبندی ریزتر لزوماً بهتر نیستند. ### یک جمله در هر خط در هر خط یک جمله بنویسید. این کار باعث میشود جملات طولانی بلافاصله قابل مشاهده باشند. همچنین از آنجا که رابط بررسی GitHub خطگرا است، بازبینی تغییرات و ارائه پیشنهادات مستقیم را آسانتر میکند. ### لینکها برای خوانایی بهتر سورس، از [لینکهای ارجاعی](https://github.github.com/gfm/#reference-link) به میزان کم، استفاده کنید. تعاریف را نزدیک به اولین استفاده از آنها قرار دهید. > <span class="admonition-kind" data-kind="admonition"></span> > > **مثال** > > ```markdown > We follow the [Diátaxis](https://diataxis.fr/) approach to structure documentation. > This framework distinguishes between [tutorials], [guides], [reference], and [explanation]. > > [tutorials]: https://diataxis.fr/tutorials/ > [guides]: https://diataxis.fr/how-to-guides/ > [reference]: https://diataxis.fr/reference/ > [explanation]: https://diataxis.fr/explanation/ > ``` مگر در مواردی که صراحتاً نیاز به اشاره به آخرین نسخه یک منبع خارجی باشد، تمام ارجاعها باید [پیوندهای دائمی](https://en.wikipedia.org/wiki/Permalink) باشند. بسیاری از سرویسهای وب پیوندهای دائمی ارائه میدهند، مانند: - [آدرسهای اینترنتی گیتهاب به کامیتهای خاص](https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files) - [آدرسهای اینترنتی ویکیپدیا به نسخههای خاصی از صفحات](https://en.wikipedia.org/wiki/Wikipedia:Linking_to_Wikipedia#Permanent_links_to_old_versions_of_pages) - [ابزار «Save Page Now» در اینترنت آرشیو برای پایدارسازی صفحات وب](https://web.archive.org/save)