Зробіть внесок до керівництва

Python Packaging User Guide запрошує контриб’юторів! Тут є багато способів, щоб допомогти, зокрема:

  • Читання керівництва і надання відгуку

  • Оцінювання нових вкладів

  • Вивірення існуючого вмісту

  • Написання нового вмісту

  • Translate the guide

Переважна більшість роботи над Python Packaging User Guide відбувається у репозиторії проєкту на GitHub. Аби розпочати, ознайомтеся з переліком відкритих іш’ю та пул реквестів. Якщо ви збираєтеся написати статтю чи відредагувати це керівництво, будь ласка, прочитайте наше керівництво зі стилю.

Здійснюючи внесок до Python Packaging User Guide, від вас очікуватиметься слідування кодексу честі PSF.

Типи документації

Цей проєкт містить чотири ясно виражені типи документації із чіткими призначеннями. Пропонуючи нові доповнення до проєкту, будь ласка, оберіть відповідний вид документації.

Навчальні інструкції

Навчальні інструкції зосереджені на навчанні читача нових концептів шляхом досягнення цілі. Це упевнені керівництва у вигляді крок-за-кроком. Вони не містять додаткових попереджень чи інформації. приклад документу у стилі навчальної інструкції.

Керівництва

Керівництва зосереджені на досягненні конкретного завдання і можуть покладатися на деякий рівень заздалегідь наявних знань. Вони подібні до навчальних інструкцій, але мають вужчий та чіткіший фокус, а також можуть перелічувати багато застережень й додаткової інформації де потрібно. Крім того, керівництва можуть розбирати багато підходів до вирішення цього завдання. приклад документу у стилі керівництва.

Обговорення

Обговорення зосереджені на роз’ясненні розумінні й інформації. Вони досліджують конкретну тему, не маючи на меті нічого конкретного. приклад документу в стилі обговорення.

Специфікації

Специфікації — це довідкова документація, орієнтована на всебічне документування погодженого інтерфейсу сумісності засобів пакування. приклад документу в стилі специфікації.

Translations

We use Weblate to manage translations of this project. Please visit the packaging.python.org project on Weblate to contribute.

If you are experiencing issues while you are working on translations, please open an issue on Github.

Порада

Any translations of this project should follow reStructuredText syntax.

Adding a language

If your language is not listed on packaging.python.org, click the button Start new translation at the bottom of the language list and add the language you want to translate.

Following reStructuredText syntax

If you are not familiar with reStructuredText (RST) syntax, please read this guide before translating on Weblate.

Do not translate the text in reference directly

When translating the text in reference, please do not translate them directly.

Wrong: Translate the following text directly:
`some ref`_ -> `TRANSLATED TEXT HERE`_
Right: Translate the following text with your own language and add the original reference:
`some ref`_ -> `TRANSLATED TEXT HERE <some ref>`_

Збирання цього керівництва локально

Хоча це й не вимагається для внесення вкладів, збирання цього керівництва локально може бути корисним аби протестувати свої зміни. Щоб зібрати це керівництво локально, вам знадобиться:

  1. Nox. You can install or upgrade nox using pip:

    python -m pip install --user nox
    
  2. Python 3.6. Our build scripts are designed to work with Python 3.6 only. See the Hitchhiker’s Guide to Python installation instructions to install Python 3.6 on your operating system.

To build the guide, run the following bash command in the source folder:

nox -s build

По завершенню процесу, ви можете знайти результуючий HTML у теці ./build/html. Ви можете відкрити файл index.html для перегляду цього керівництва у веб-оглядачі, втім рекомендується отримувати доступ до керівництва через HTTP сервер.

You can build the guide and serve it via an HTTP server using the following command:

nox -s preview

Керівництво можна буде переглядати через http://localhost:8000.

Куди це керівництво публікується

Це керівництво розгорнуте через ReadTheDocs і конфігурація живе на https://readthedocs.org/projects/python-packaging-user-guide/. Доступ до нього надається із додаткового домену через фронт-енд Fast.ly.

Керівництво по стилю

Це керівництво зі стилю містить поради щодо того, як вам слід писати Python Packaging User Guide. Перш, ніж почати, ознайомтеся з ним. Дотримуючись цього керівництва по стилю, ваші внески допоможуть доповнити єдине ціле і спростять їх схвалення для проєкту.

Призначення

Python Packaging User Guide має на меті бути авторитетним ресурсом щодо того як пакувати, публікувати та встановлювати проєкти на Python, використовуючи сучасні засоби.

Охоплення

Керівництво має відповісти на запитання і вирішити проблеми за допомогою точних і влучних порад.

Керівництво не має бути всеосяжним і не має на меті замінити документацію окремих проєктів. Наприклад, pip містить дюжини команд, опцій та налаштувань. Документація pip ретельно описує кожну з них, тоді як це керівництво описує лише частини pip, що необхідні для виконання конкретних завдань, описаних у цьому керівництві.

Читачі

Цільова аудиторія цього керівництва — усі, хто користується Pythonом із пакунками.

Не забувайте, що Python-спільнота — велика і привітна. Читачі можуть бути іншого віку, статі, мати іншу освіту та належати іншій культурі, ніж ви, але вони так само заслуговують дізнаватися про пакування, як і ви.

Зокрема, пам’ятайте, що не усі люди, які використовують Python, вважають себе програмістами. До читачів цього керівництва можуть належати астрономи, художники, учні так само, як і професійні розробники програмного забезпечення.

Вираження і тон

Під час написання цього керівництва, намагайтеся виражатися доступно й скромно, навіть якщо у вас є усі відповіді.

Уявіть, що ви працюєте над Python-проєктом з кимось, кого знаєте як розумну людину з потужними навичками. Вам подобається працювати з цією людиною, як і їй подобається працювати із вами. Ця людина спитала вас і ви знаєте відповідь. Як би ви відповідали? Саме так і варто писати це керівництво.

Ось швидка перевірка: спробуйте прочитати вголос, щоб відчути виразність і тон свого письма. Чи звучить це як щось, що ви б сказали, або ж це звучить так, ніби ви граєте роль чи виголошуєте промову? Не соромтеся скористатися скороченнями і не турбуйтеся про дотримання вимогливих граматичних правил. Цим вам дозволено закінчити речення прийменником, якщо саме так ви бажаєте його закінчити.

Під час написання керівництва, підлаштуйте свій тон на серйозність і складність теми. Якщо ви пишете вступну навчальну інструкцію, можна пожартувати, однак якщо ви покриваєте делікатну рекомендацію щодо безпеки, можливо, вам захочеться взагалі уникнути жартів.

Домовленості й механіка

Звертайтеся до читачів

Коли ви даєте рекомендації або вказуєте необхідні кроки, звертайтеся до читачів на ви або використовуйте наказовий спосіб.

Неправильно: Для встановлення, користувач запускає …
Правильно: Ви можете встановити це, виконавши …
Правильно: Щоб встановити це, виконайте…
Оголошуйте припущення

Уникайте невисловлених припущень. Читання в Інтернеті означає, що яка завгодно сторінка керівництва може бути найпершою його сторінкою, яку читач побачить узагалі. Якщо ж ви збираєтеся робити припущення, то скажіть, на які саме припущення ви покладаєтесь.

Щедро додавайте перехресні посилання

Коли ви вперше згадуєте інструмент або підхід, дайте посилання на ту частину керівництва, яка розповідає про нього, або ж на відповідну документацію деінде. Не змушуйте читачів шукати інформацію.

Дотримуйтеся практик іменування

Згадуючи інструменти, сайти, людей чи інші власні назви, використовуйте їх бажане написання великих літер.

Неправильно: Pip використовує…
Правильно: pip використовує…

Неправильно: …розміщено на github.
Правильно: …розміщено на GitHub.
Використовуйте ґендерно нейтральний стиль

Часто ви звертатиметеся до читача безпосередньо за допомогою ви і ваш. В інших випадках використовуйте гендерно-нейтральні займенники вони та їх, чи повністю уникайте займенників.

Неправильно: Доглядач завантажує файл. А потім він…
Правильно: Доглядачі завантажують файл. А потім вони…
Правильно: Доглядачі завантажують файл. А потім ці доглядачі…
Заголовки

Пишіть заголовки за допомогою слів, які читачі шукатимуть. Хороший спосіб це зробити — скласти заголовок так, щоб він доповнював неявне запитання. Наприклад, читачі можуть хотіти дізнатися Як я можу встановити MyLibrary?, тож хорошим заголовком буде Встановити MyLibrary.

У заголовках розділів, дотримуйтеся регістру речень. Іншими словами, пишіть заголовки так, як ви б написали звичайне речення.

Неправильно: Речі, Які Вам Слід Знати Про Python
Правильно: Речі, які вам слід знати про Python
Числа

У всередині тексту, пишіть числа від одного до дев’яти словами. Для інших чисел або чисел у таблицях використовуйте цифри.