انواع راهنما
مستندات یکجور نوشته نیستند: یکی درس میدهد، یکی راه نشان میدهد، یکی فقط فهرست میکند. اگر اسم هر بخش را بشناسی، میدانی برای سؤالت باید کدام را باز کنی.
عنوانهای ingدار
عنوان بخشهای مستندات خیلی وقتها یک فعل با ing است: Getting Started، Installing Python، Writing Your First Test. اینجا ing زمان حال استمراری نیست؛ از فعل یک اسم میسازد: Installing Python یعنی «نصبِ پایتون». پس عنوان را مثل اسم یک کار بخوان، نه مثل یک جمله.
هشت کلمهی این درس
documentation (داکیومِنتِیشِن): مستندات؛ نوشتههای راهنمای یک ابزار
document در انگلیسی یعنی سند و نوشته. documentation همهی نوشتههایی است که سازندههای یک زبان، کتابخانه یا برنامه مینویسند تا بگویند چطور کار میکند و چطور باید از آن استفاده کنی. برنامهنویسها کوتاهش میکنند و میگویند docs. وقتی نمیدانی یک تابع چه میگیرد و چه پس میدهد، اولین جای درست برای نگاه کردن همینجاست.
Please read the documentation before you open a new issue.
لطفاً قبل از اینکه یک issue تازه باز کنی، مستندات را بخوان.
guide (گاید): راهنما؛ نوشتهای که یک کار را یاد میدهد
guide در انگلیسی هم به آدمِ راهنما میگویند (مثل راهنمای تور) و هم به نوشتهی راهنما. در مستندات، guide صفحهای است که یک موضوع را از اول تا آخر توضیح میدهد، مثلاً «راهنمای نصب» یا «راهنمای کار با فرمها». فرقش با reference این است که guide مثل معلم قدمبهقدم جلو میرود، ولی reference مثل فرهنگ لغت فقط فهرست میکند.
Follow the installation guide to set up the project on Windows.
برای راهاندازی پروژه روی ویندوز، راهنمای نصب را دنبال کن.
tutorial (توتوریِل): آموزش قدمبهقدم با ساختن یک چیز
tutor در انگلیسی یعنی معلم خصوصی. tutorial درسی است که دستت را میگیرد و با هم یک چیز کوچک میسازید: یک صفحهی وب، یک بازی ساده، یک ربات. لازم نیست از قبل چیزی بدانی؛ فقط خط به خط جلو میروی. بیشتر مستندات یک بخش Tutorial برای تازهواردها دارند و ویدیوهای آموزشی یوتیوب را هم tutorial میگویند.
This tutorial shows you how to build a simple chat app.
این آموزش نشانت میدهد چطور یک برنامهی چت ساده بسازی.
reference (رِفِرِنس): مرجع؛ فهرست کامل تابعها و گزینهها
refer یعنی «رجوع کردن». reference بخشی از مستندات است که مثل فرهنگ لغت به آن رجوع میکنی: همهی تابعها، ورودیها، خروجیها و خطاهایشان پشت سر هم و بدون داستان. آن را از اول تا آخر نمیخوانی؛ وقتی اسم یک تابع را میدانی و جزئیاتش را میخواهی سراغش میروی. معمولاً اسمش API Reference است.
See the API reference for a full list of parameters.
برای فهرست کامل پارامترها، مرجع API را ببین.
example (ایگزَمپِل): مثال؛ نمونه
example یعنی مثال. در مستندات، زیر توضیح هر تابع یک بخش Example یا Examples هست که چند خط کد آماده نشان میدهد. خیلی وقتها خواندن همین چند خط از خواندن کل توضیح سریعتر جواب میدهد. در نشانیهای نمونه هم آن را میبینی: example.com دامنهای است که فقط برای مثال زدن کنار گذاشته شده.
The following example reads a file line by line.
مثال زیر یک فایل را خط به خط میخواند.
getting started (گِتینگ اِستارتِد): شروع کار؛ اولین قدمها
get started یعنی «دست به کار شدن». Getting Started اسم اولین صفحهی بیشتر مستندات است: چطور نصب کنی، اولین برنامه را چطور بنویسی و چطور اجرا کنی. اگر با یک ابزار تازه روبهرو شدی و نمیدانی از کجا شروع کنی، دنبال همین عنوان بگرد.
New to the library? Read the Getting Started page first.
با این کتابخانه تازه آشنا شدهای؟ اول صفحهی «شروع کار» را بخوان.
overview (اُووِرویو): نگاه کلی؛ مرور کوتاه
over یعنی «از بالا» و view یعنی «نگاه». overview نگاهی از بالا به کل ماجراست: صفحهای کوتاه که میگوید این ابزار چیست، چه بخشهایی دارد و هر بخش به چه کاری میآید، بدون رفتن سراغ جزئیات. مثل نقشهی یک شهر قبل از قدم زدن در کوچههایش.
This page gives a short overview of the main features.
این صفحه مرور کوتاهی از قابلیتهای اصلی میدهد.
quick start (کوئیک اِستارت): شروع سریع؛ کوتاهترین راه تا اولین اجرا
quick یعنی سریع. Quick Start بخشی است که در چند خط تو را به اولین نتیجه میرساند: این را نصب کن، این سه خط را بنویس، اجرا کن. توضیح زیادی نمیدهد و فقط میخواهد در پنج دقیقه چیزی را روی صفحه ببینی. توضیحهای کاملتر در guide و reference میآید.
The quick start takes about five minutes to complete.
تمام کردن بخش «شروع سریع» حدود پنج دقیقه طول میکشد.
صفحهی اول مستندات
Welcome to the PixelKit documentation!
New here? Start with the Overview to see what PixelKit can do. Then open the Quick Start: it takes five minutes and ends with a working example.
The Tutorial teaches you step by step how to build a small game. Each guide explains one topic, such as sound or animation.
Do you already know the basics? Go to the API Reference. It lists every function with its parameters.
به مستندات PixelKit خوش آمدی!
تازه آمدهای؟ با «نگاه کلی» شروع کن تا ببینی PixelKit چه کارهایی میتواند بکند. بعد «شروع سریع» را باز کن: پنج دقیقه طول میکشد و آخرش یک مثال داری که کار میکند.
«آموزش» قدمبهقدم یادت میدهد چطور یک بازی کوچک بسازی. هر «راهنما» یک موضوع را توضیح میدهد، مانند صدا یا انیمیشن.
اصول را از قبل بلدی؟ سراغ «مرجع API» برو. آنجا همهی تابعها با پارامترهایشان فهرست شدهاند.