README
README اولین چیزی است که هر کس از پروژهی تو میبیند. این هشت کلمه تیتر بخشهای آن هستند؛ اگر بشناسیشان، هم README هر پروژهای را سریع میخوانی و هم مال خودت را مینویسی.
تیتر با اسم، دستور با فعل امری
تیترهای README اسم هستند یا شکل -ing که کار اسم را میکند: Introduction، Installation، Contributing، Getting Started. کلمههای اصلی تیتر با حرف بزرگ شروع میشوند (Table of Contents). ولی زیر تیتر، دستورها با فعل امری میآیند: «Clone the repository»، «Run the tests». توضیح پروژه هم با زمان حال ساده است: «Weather Bot is…».
هشت کلمهی این درس
introduction (اینترُداکشِن): مقدمه، معرفی
introduction اسمِ فعل introduce (معرفی کردن) است و یعنی مقدمه: اولین بخش یک متن که میگوید موضوع چیست. در README، مقدمه دو سه جمله است که جواب سه سؤال را میدهد: این پروژه چیست، برای چه کسی است و چه مشکلی را حل میکند. اگر خواننده فقط همین بخش را بخواند، باید بفهمد به دردش میخورد یا نه.
The introduction explains what the project does in two sentences.
مقدمه در دو جمله توضیح میدهد که پروژه چه کار میکند.
table of contents (تِیبِل آو کانتِنتس): فهرست مطالب
table اینجا یعنی «فهرست» (نه میز) و contents یعنی «چیزهای درون» یک کتاب یا سند. table of contents همان فهرست مطالب اول کتاب است. در README بلند، بعد از مقدمه فهرستی از لینک به بخشها میگذارند تا خواننده مستقیم به بخشی که میخواهد بپرد. کوتاهشدهاش TOC است.
Use the table of contents to jump to the installation section.
از فهرست مطالب استفاده کن تا به بخش نصب بپری.
screenshot (اِسکرینشات): عکسی که از صفحهی نمایش گرفته میشود
screen یعنی صفحهی نمایش و shot یعنی عکس گرفتن؛ screenshot عکسی است که از خود صفحه میگیری. در README یک screenshot از برنامه بهتر از ده خط توضیح است. در گزارش باگ هم همیشه کمک میکند؛ فقط برای پیام خطا، متن آن را هم کپی کن، چون متنِ درون عکس را نمیشود جستوجو یا کپی کرد.
Please add a screenshot of the error to the bug report.
لطفاً یک اسکرینشات از خطا به گزارش باگ اضافه کن.
demo (دِمو): نمایش زنده یا نسخهی نمونهی یک برنامه
demo کوتاهشدهی demonstration (نشان دادن) است. دو معنی نزدیک به هم دارد: یکی نسخهای از برنامه که میتوانی همین الان امتحانش کنی (live demo)، و دیگری جلسهای که در آن کار خودت را به تیم یا مشتری نشان میدهی. در README یک لینک demo باعث میشود آدمها قبل از نصب، برنامه را ببینند.
You can try the live demo before you install anything.
قبل از اینکه چیزی نصب کنی، میتوانی نسخهی نمایشی زنده را امتحان کنی.
contributing (کانتریبیوتینگ): راهنمای مشارکت در پروژه
contribute یعنی سهم داشتن و کمک کردن به یک کار مشترک. در پروژههای متنباز، بخش Contributing (یا فایل CONTRIBUTING.md) به تازهواردها میگوید چطور کمک کنند: باگ را کجا گزارش بدهند، کد را با چه سبکی بنویسند و pull request را چطور بفرستند. قبل از اولین کمک به هر پروژه، این بخش را بخوان.
Read the contributing guide before you open a pull request.
قبل از باز کردن pull request، راهنمای مشارکت را بخوان.
credits (کرِدیتس): قدردانی از سازندهها و منبعها
credit یعنی «اعتبار»؛ give credit یعنی بگویی این کار مال چه کسی است. credits همان فهرست اسمهایی است که آخر فیلم بالا میرود. در README این بخش میگوید از کار چه کسانی استفاده شده: آیکونها، فونتها، کتابخانهها و آدمهایی که کمک کردهاند. نوشتنش هم ادب است و هم خیلی وقتها شرط مجوز.
The icons are free, but you must mention the author in the credits.
آیکونها رایگاناند، ولی باید اسم سازنده را در بخش قدردانی بیاوری.
roadmap (رُودمَپ): نقشهی راه؛ برنامهی آیندهی پروژه
road یعنی جاده و map یعنی نقشه؛ roadmap در اصل نقشهی جادههاست. در پروژهها یعنی فهرستی از کارهایی که قرار است در آینده انجام شود و ترتیب آنها. در README به خواننده میگوید پروژه به کدام سمت میرود و چه چیزی هنوز آماده نیست، تا برای قابلیتی که در راه است دوباره درخواست ننویسد.
Dark mode is on the roadmap for the next release.
حالت تاریک در نقشهی راهِ انتشار بعدی هست.
FAQ (اِفاِیکیو): پرسشهای پرتکرار
FAQ کوتاهشدهی Frequently Asked Questions است: «سؤالهایی که زیاد پرسیده میشوند». بخشی است که سؤالهای تکراری کاربرها را با جوابشان یکجا جمع میکند، تا هر کس قبل از پرسیدن اول آنجا را نگاه کند. قبل از اینکه در یک پروژه issue باز کنی، FAQ را بخوان؛ شاید جوابت همانجا باشد.
Check the FAQ first, your question may already be answered there.
اول پرسشهای پرتکرار را نگاه کن؛ شاید سؤالت همانجا جواب داده شده باشد.
README یک پروژهی کوچک
# Weather Bot
## Introduction
Weather Bot is a small chat bot that tells you the weather. See the screenshot below, or try the live demo at https://demo.example.com.
## Table of Contents
- Installation
- Usage
- FAQ
## Roadmap
- [x] Daily forecast
- [ ] Persian language
## Contributing
Pull requests are welcome. Please open an issue first.
## Credits
Icons by Sara Ahmadi.
# ربات هواشناسی
## مقدمه
Weather Bot یک ربات چت کوچک است که وضع هوا را به تو میگوید. اسکرینشات پایین را ببین، یا نسخهی نمایشی زنده را در https://demo.example.com امتحان کن.
## فهرست مطالب
- نصب
- روش استفاده
- پرسشهای پرتکرار
## نقشهی راه
- [x] پیشبینی روزانه
- [ ] زبان فارسی
## مشارکت
از pull request استقبال میکنیم. لطفاً اول یک issue باز کن.
## قدردانی
آیکونها از سارا احمدی.