diff --git a/docs/labs/networking/lab8-samba.uk.md b/docs/labs/networking/lab8-samba.uk.md index b1fdb027a2..d23f151192 100644 --- a/docs/labs/networking/lab8-samba.uk.md +++ b/docs/labs/networking/lab8-samba.uk.md @@ -1,7 +1,7 @@ --- author: Wale Soyinka contributors: Ganna Zhyrnova -tested on: All Versions +tested on: Всі версії tags: - samba - cifs @@ -9,22 +9,22 @@ tags: - nmbd - smb.conf - smbpasswd - - network file system + - файлова система мережі --- # Лабораторна робота 8: Samba -## Objectives +## Цілі -After completing this lab, you will be able to +Виконавши цю лабораторну роботу, ви зможете - встановити та налаштувати Samba - обмінюватися файлами та каталогами між системами Linux за допомогою Samba - використовувати звичайні утиліти Samba -Estimated time to complete this lab: 40 minutes +Приблизний час виконання цієї лабораторної роботи: 40 хвилин -## Introduction +## Вступ Samba дозволяє обмінюватися файлами та виконувати служби друку між системами Unix/Linux і Windows. @@ -37,21 +37,21 @@ _nmbd_: цей демон забезпечує обслуговування ім Вправи в цій лабораторній роботі зосереджені на налаштуванні Samba як сервера та клієнта на сервері Rocky Linux. -## Exercise 1 +## Завдання 1 ### Встановіть Samba та налаштуйте базовий спільний каталог #### Щоб встановити серверну програму Samba 0. Використовуйте утиліту dnf, щоб установити сервер Samba та пакет клієнта на вашому сервері. - Type: + Впишіть: ```bash sudo dnf install -y samba ``` #### Щоб налаштувати Samba -1. Створіть каталог під назвою samba-share у папці /tmp, до якої потрібно надати спільний доступ. Type: +1. Створіть каталог під назвою samba-share у папці /tmp, до якої потрібно надати спільний доступ. Впишіть: ```bash mkdir /tmp/samba-share @@ -84,7 +84,7 @@ _nmbd_: цей демон забезпечує обслуговування ім sudo systemctl status smb nmb ``` -## Exercise 2 +## Завдання 2 ### Користувачі Samba @@ -94,13 +94,13 @@ _nmbd_: цей демон забезпечує обслуговування ім #### Щоб створити користувача Samba та пароль Samba -1. Спочатку створіть звичайного системного користувача з іменем sambarockstar. Type: +1. Спочатку створіть звичайного системного користувача з іменем sambarockstar. Впишіть: ```bash sudo useradd sambarockstar ``` -2. Переконайтеся, що користувача було створено правильно. Type: +2. Переконайтеся, що користувача було створено правильно. Впишіть: ```bash id sambarockstar ``` @@ -118,7 +118,7 @@ _nmbd_: цей демон забезпечує обслуговування ім sudo systemctl restart smb nmb ``` -## Exercise 3 +## Завдання 3 ### Доступ до Samba Share (локальний тест) @@ -147,30 +147,30 @@ _nmbd_: цей демон забезпечує обслуговування ім sudo mount -t cifs //localhost/Shared ~/samba-client -o user=sambarockstar ``` -2. Використовуйте команду `mount`, щоб отримати список усіх змонтованих файлових систем типу CIFS. Type: +2. Використовуйте команду `mount`, щоб отримати список усіх змонтованих файлових систем типу CIFS. Впишіть: ```bash mount -t cifs ``` - OUTPUT + ВИХІД ```bash //localhost/Shared on ~/samba-client type cifs (rw,relatime,vers=3.1.1,cache=strict,username=sambarockstar.... ...... ``` -3. Подібним чином скористайтеся командою `df`, щоб переконатися, що змонтований спільний ресурс доступний. Type: +3. Подібним чином скористайтеся командою `df`, щоб переконатися, що змонтований спільний ресурс доступний. Впишіть: ```bash df -t cifs ``` - OUTPUT: + Вихід: ``` Filesystem 1K-blocks Used Available Use% Mounted on //localhost/Shared 73364480 17524224 55840256 24% ~/samba-client ``` -4. Далі перелічіть вміст підключеного спільного ресурсу. Type: +4. Далі перелічіть вміст підключеного спільного ресурсу. Впишіть: ```bash ls ~/samba-client @@ -182,7 +182,7 @@ _nmbd_: цей демон забезпечує обслуговування ім touch ~/samba-client/testfile.txt ``` -## Exercise 4 +## Завдання 4 ### Змінення дозволів на спільний доступ @@ -206,7 +206,7 @@ _nmbd_: цей демон забезпечує обслуговування ім touch ~/samba-client/testfile2.txt ``` -## Exercise 5 +## Завдання 5 ### Використання Samba для певних груп користувачів @@ -214,18 +214,18 @@ _nmbd_: цей демон забезпечує обслуговування ім #### Щоб створити нову групу для користувача Samba -1. Скористайтеся утилітою groupadd, щоб створити нову системну групу під назвою rockstars. Ми будемо використовувати цю групу в нашому прикладі для користувачів житлової системи, які мають доступ до певного ресурсу. Type: +1. Скористайтеся утилітою groupadd, щоб створити нову системну групу під назвою rockstars. Ми будемо використовувати цю групу в нашому прикладі для користувачів житлової системи, які мають доступ до певного ресурсу. Впишіть: ```bash sudo groupadd rockstars ``` -2. Додайте існуючого користувача системи/Samba до групи. Type: +2. Додайте існуючого користувача системи/Samba до групи. Впишіть: ```bash sudo usermod -aG rockstars sambarockstar ``` #### Щоб налаштувати дійсних користувачів у конфігурації Samba -1. Скористайтеся утилітою sed, щоб додати новий дійсний параметр користувача до визначення спільного доступу у файлі конфігурації Samba. Type: +1. Скористайтеся утилітою sed, щоб додати новий дійсний параметр користувача до визначення спільного доступу у файлі конфігурації Samba. Впишіть: ```bash sudo sed -i '/\[Shared\]/a valid users = @sambagroup' /etc/samba/smb.conf ``` @@ -235,7 +235,7 @@ _nmbd_: цей демон забезпечує обслуговування ім ``` 3. Тепер протестуйте доступ до спільного ресурсу за допомогою sambarockstar і перевірте доступ. -## Exercise 6 +## Завдання 6 Ця вправа імітує реальний сценарій, у якому ви діятимете як адміністратор клієнтської системи, а потім тестуватимете доступ до служби Samba на віддаленій системі (serverHQ), до якої у вас немає адміністративного доступу чи привілеїв. Будучи студентом, ви налаштуєте клієнт Samba на своїй машині (serverXY) для доступу до служби Samba, розміщеної на іншій машині (serverHQ). Це відображає стандартні налаштування робочого місця. diff --git a/docs/labs/systems_administration_II/lab4-advanced_system_process_monitoring.uk.md b/docs/labs/systems_administration_II/lab4-advanced_system_process_monitoring.uk.md index 6ca879ad63..0dd890d80e 100644 --- a/docs/labs/systems_administration_II/lab4-advanced_system_process_monitoring.uk.md +++ b/docs/labs/systems_administration_II/lab4-advanced_system_process_monitoring.uk.md @@ -1,10 +1,10 @@ --- author: Wale Soyinka contributors: Steven Spencer, Ganna Zhrynova -tested on: All Versions +tested on: Всі версії tags: - - system monitoring - - process monitoring + - моніторинг системи + - моніторинг процесу - fuser - numactl - perf @@ -19,9 +19,9 @@ tags: # Лабораторна робота 4: Розширений моніторинг системи та процесів -## Objectives +## Цілі -After completing this lab, you will be able to +Виконавши цю лабораторну роботу, ви зможете - переглядати та керувати процесами за допомогою передових інструментів - діагностувати та налагоджувати системні виклики @@ -29,15 +29,15 @@ After completing this lab, you will be able to - переглядати та встановлювати власні політики планування для процесів - аналізувати продуктивність системи та додатків -Estimated time to complete this lab: 90 minutes +Приблизний час виконання цієї лабораторної роботи: 90 хвилин -## Introduction +## Вступ Команди в цій лабораторній роботі охоплюють ширший спектр керування процесами, моніторингу системи та керування ресурсами в Linux. Вони додають більшої глибини та різноманітності вашому репертуару системного адміністратора. Ці вправи охоплюють додаткові команди та поняття Linux, надаючи практичний досвід керування процесами, моніторингу ресурсів і розширеного контролю. -## Exercise 1 +## Завдання 1 ### fuser @@ -45,13 +45,13 @@ Estimated time to complete this lab: 90 minutes #### Щоб створити сценарій для імітації використання файлу -1. Спочатку створіть порожній тестовий файл, до якого ми хочемо отримати доступ. Type: +1. Спочатку створіть порожній тестовий файл, до якого ми хочемо отримати доступ. Впишіть: ```bash touch ~/testfile.txt ``` -2. Створіть сценарій, який ми будемо використовувати для імітації доступу до testfile.txt. Type: +2. Створіть сценарій, який ми будемо використовувати для імітації доступу до testfile.txt. Впишіть: ```bash cat > ~/simulate_file_usage.sh << EOF @@ -60,13 +60,13 @@ Estimated time to complete this lab: 90 minutes EOF ``` -3. Make the script executable. Type: +3. Зробіть сценарій виконуваним. Впишіть: ```bash chmod +x ~/simulate_file_usage.sh ``` -4. Запустіть скрипт. Type: +4. Запустіть скрипт. Впишіть: ```bash ~/simulate_file_usage.sh & @@ -80,13 +80,13 @@ Estimated time to complete this lab: 90 minutes fuser ~/testfile.txt ``` -2. Перегляньте додаткові параметри `fuser` за допомогою параметра `-v`. Type: +2. Перегляньте додаткові параметри `fuser` за допомогою параметра `-v`. Впишіть: ```bash fuser -v ~/testfile.txt ``` -3. Перегляньте додаткові параметри `fuser` за допомогою параметра `-v`. Тепер ви можете видалити файли. Type: +3. Перегляньте додаткові параметри `fuser` за допомогою параметра `-v`. Тепер ви можете видалити файли. Впишіть: ```bash kill %1 @@ -95,13 +95,13 @@ Estimated time to complete this lab: 90 minutes #### Щоб ідентифікувати процес, який отримує доступ до порту TCP/UDP -1. Використовуйте команду `fuser`, щоб визначити процес доступу до TCP-порту 22 на вашому сервері. Type: +1. Використовуйте команду `fuser`, щоб визначити процес доступу до TCP-порту 22 на вашому сервері. Впишіть: ```bash sudo fuser 22/tcp ``` -## Exercise 2 +## Завдання 2 ### `perf` @@ -109,7 +109,7 @@ Estimated time to complete this lab: 90 minutes #### Щоб встановити `perf` -1. Встановіть програму `perf`, якщо вона не встановлена на вашому сервері. Type: +1. Встановіть програму `perf`, якщо вона не встановлена на вашому сервері. Впишіть: ```bash sudo dnf -y install perf @@ -154,7 +154,7 @@ Estimated time to complete this lab: 90 minutes ~/generate_cpu_load.sh 50 & ``` -2. Повторно запустіть сценарій, але використовуйте `perf`, щоб записати продуктивність сценарію для аналізу використання ЦП та інших показників. Type: +2. Повторно запустіть сценарій, але використовуйте `perf`, щоб записати продуктивність сценарію для аналізу використання ЦП та інших показників. Впишіть: ```bash @@ -167,7 +167,7 @@ Estimated time to complete this lab: 90 minutes #### Для аналізу даних про ефективність і моніторингу подій у реальному часі -1. Використовуйте команду `perf report`, щоб переглянути звіт про продуктивність, щоб зрозуміти шаблони використання процесора та пам’яті. Type: +1. Використовуйте команду `perf report`, щоб переглянути звіт про продуктивність, щоб зрозуміти шаблони використання процесора та пам’яті. Впишіть: ```bash sudo perf report @@ -176,7 +176,7 @@ Estimated time to complete this lab: 90 minutes Ви можете використовувати різні клавіші клавіатури для подальшого вивчення звіту. Введіть ++"q"++, щоб вийти з інтерфейсу перегляду звітів `perf`. -2. Спостерігайте/фіксуйте події кешу процесора в режимі реального часу протягом 40 секунд, щоб виявити потенційні вузькі місця продуктивності. Type: +2. Спостерігайте/фіксуйте події кешу процесора в режимі реального часу протягом 40 секунд, щоб виявити потенційні вузькі місця продуктивності. Впишіть: ```bash sudo perf stat -e cache-references,cache-misses sleep 40 @@ -184,7 +184,7 @@ Estimated time to complete this lab: 90 minutes #### Щоб записати повну продуктивність системи -1. Збирайте дані про продуктивність усієї системи, які можна використовувати для додаткового аналізу. Type: +1. Збирайте дані про продуктивність усієї системи, які можна використовувати для додаткового аналізу. Впишіть: ```bash sudo perf record -a sleep 10 @@ -196,13 +196,13 @@ Estimated time to complete this lab: 90 minutes sudo perf stat -e cycles find /proc ``` -3. Зробіть те саме, але зі сценарієм ./generate_cpu_load.sh. Підраховуйте певні події, як-от цикли ЦП, щоб оцінити продуктивність сценарію ./generate_cpu_load.sh. Type: +3. Зробіть те саме, але зі сценарієм ./generate_cpu_load.sh. Підраховуйте певні події, як-от цикли ЦП, щоб оцінити продуктивність сценарію ./generate_cpu_load.sh. Впишіть: ```bash sudo perf stat -e cycles ./generate_cpu_load.sh 500 ``` - OUTPUT: + Вихід: ```bash ...... @@ -237,7 +237,7 @@ Estimated time to complete this lab: 90 minutes kill %1 ``` -## Exercise 3 +## Завдання 3 ### `strace` @@ -245,7 +245,7 @@ Estimated time to complete this lab: 90 minutes #### Щоб створити сценарій для дослідження `strace` -1. Створіть простий сценарій під назвою `strace_script.sh` і зробіть його виконуваним. Type: +1. Створіть простий сценарій під назвою `strace_script.sh` і зробіть його виконуваним. Впишіть: ```bash cat > ~/strace_script.sh << EOF @@ -260,7 +260,7 @@ Estimated time to complete this lab: 90 minutes #### Щоб використовувати `strace` для запущених процесів -1. Запустіть сценарій і прикріпіть `strace`. Type: +1. Запустіть сценарій і прикріпіть `strace`. Впишіть: ```bash ~/strace_script.sh & @@ -272,7 +272,7 @@ Estimated time to complete this lab: 90 minutes export MYPID=$(pgrep strace_script) ; echo $MYPID ``` - OUTPUT: + Вихід: ```bash 4006301 @@ -286,7 +286,7 @@ Estimated time to complete this lab: 90 minutes 4. Від’єднайте або зупиніть процес `strace`, ввівши ++ctrl+c++ -5. Вихід `strace` можна відфільтрувати, зосередившись на певних системних викликах, таких як `open` і `read`, щоб проаналізувати їх поведінку. Спробуйте зробити це для системних викликів `open` і `read`. Type: +5. Вихід `strace` можна відфільтрувати, зосередившись на певних системних викликах, таких як `open` і `read`, щоб проаналізувати їх поведінку. Спробуйте зробити це для системних викликів `open` і `read`. Впишіть: ```bash sudo strace -e trace=open,read -p $MYPID @@ -302,7 +302,7 @@ Estimated time to complete this lab: 90 minutes #### Для аналізу частоти системних викликів -1. Узагальніть кількість системних викликів, щоб визначити системні виклики, які найчастіше використовуються процесом. Зробіть це лише на 10 секунд, додавши команду `timeout`. Type: +1. Узагальніть кількість системних викликів, щоб визначити системні виклики, які найчастіше використовуються процесом. Зробіть це лише на 10 секунд, додавши команду `timeout`. Впишіть: ```bash sudo timeout 10 strace -c -p $MYPID @@ -310,7 +310,7 @@ Estimated time to complete this lab: 90 minutes Наша зразкова система показує підсумковий звіт таким чином: - OUTPUT: + Вихід: ```bash strace: Process 4006301 attached @@ -334,7 +334,7 @@ Estimated time to complete this lab: 90 minutes rm ~/strace_script.sh ~/strace_output.txt ``` -## Exercise 4 +## Завдання 4 ### `atop` @@ -342,7 +342,7 @@ Estimated time to complete this lab: 90 minutes #### Щоб запустити та дослідити `atop` -1. Встановіть програму `atop`, якщо вона не встановлена на вашому сервері. Type: +1. Встановіть програму `atop`, якщо вона не встановлена на вашому сервері. Впишіть: ```bash sudo dnf -y install atop @@ -358,7 +358,7 @@ Estimated time to complete this lab: 90 minutes Використовуйте 'm', 'd' або 'n' для перемикання між переглядами пам'яті, диска або мережі. Спостерігайте, як використовуються ресурси в реальному часі. -4. Відстежуйте продуктивність системи з користувацьким інтервалом у 2 секунди, що дозволяє більш детально переглядати діяльність системи. Type: +4. Відстежуйте продуктивність системи з користувацьким інтервалом у 2 секунди, що дозволяє більш детально переглядати діяльність системи. Впишіть: ```bash sudo atop 2 @@ -366,7 +366,7 @@ Estimated time to complete this lab: 90 minutes 5. Перемикайтеся між різними видами ресурсів, щоб зосередитися на конкретних аспектах продуктивності системи. -6. Створіть звіт із файлу журналу про діяльність системи, збираючи дані кожні 60 секунд, тричі. Type: +6. Створіть звіт із файлу журналу про діяльність системи, збираючи дані кожні 60 секунд, тричі. Впишіть: ```bash sudo atop -w /tmp/atop_log 60 3 @@ -384,7 +384,7 @@ Estimated time to complete this lab: 90 minutes sudo rm /tmp/atop_log ``` -## Exercise 5 +## Завдання 5 ### `numactl` @@ -395,7 +395,7 @@ NUMA означає "нерівномірний доступ до пам'яті" #### Щоб встановити `numactl` -1. Встановіть програму `numactl`, якщо вона не встановлена на вашому сервері. Type: +1. Встановіть програму `numactl`, якщо вона не встановлена на вашому сервері. Впишіть: ```bash sudo dnf -y install numactl @@ -403,7 +403,7 @@ NUMA означає "нерівномірний доступ до пам'яті" #### Для створення сценарію, що потребує великої кількості пам’яті -1. Створіть простий сценарій, який допоможе імітувати робоче навантаження з інтенсивним використанням пам’яті на вашому сервері. Type: +1. Створіть простий сценарій, який допоможе імітувати робоче навантаження з інтенсивним використанням пам’яті на вашому сервері. Впишіть: ```bash cat > ~/memory_intensive.sh << EOF @@ -446,7 +446,7 @@ NUMA означає "нерівномірний доступ до пам'яті" rm ~/memory_intensive.sh ``` -## Exercise 6 +## Завдання 6 ### `iotop` @@ -454,7 +454,7 @@ NUMA означає "нерівномірний доступ до пам'яті" #### Щоб встановити `iotop` -1. Встановіть утиліту `iotop`, якщо вона не встановлена. Type: +1. Встановіть утиліту `iotop`, якщо вона не встановлена. Впишіть: ```bash sudo dnf -y install iotop @@ -462,7 +462,7 @@ NUMA означає "нерівномірний доступ до пам'яті" #### Щоб використовувати `iotop` для моніторингу дискового введення-виведення -1. Запустіть команду `iotop` без будь-яких параметрів, щоб використовувати її в інтерактивному режимі за замовчуванням. Type: +1. Запустіть команду `iotop` без будь-яких параметрів, щоб використовувати її в інтерактивному режимі за замовчуванням. Впишіть: ```bash sudo iotop @@ -498,7 +498,7 @@ NUMA означає "нерівномірний доступ до пам'яті" Обговоріть вплив дискового вводу-виводу на загальну продуктивність системи та як такі інструменти, як `iotop`, можуть допомогти в оптимізації системи. ``` -## Exercise 7 +## Завдання 7 ### `cgroups` @@ -508,13 +508,13 @@ NUMA означає "нерівномірний доступ до пам'яті" ### Для вивчення файлової системи `cgroup` -1. Використовуйте команду `ls`, щоб дослідити вміст і структуру файлової системи `cgroup`. Type: +1. Використовуйте команду `ls`, щоб дослідити вміст і структуру файлової системи `cgroup`. Впишіть: ```bash ls /sys/fs/cgroup/ ``` -2. Знову скористайтеся командою `ls`, щоб отримати список папок \*.slice у файловій системі `cgroup`. Type: +2. Знову скористайтеся командою `ls`, щоб отримати список папок \*.slice у файловій системі `cgroup`. Впишіть: ```bash ls -d /sys/fs/cgroup/*.slice @@ -530,7 +530,7 @@ NUMA означає "нерівномірний доступ до пам'яті" sudo mkdir -p /sys/fs/cgroup/exercise_group ``` -2. Тепер перелічіть файли та каталоги в структурі /sys/fs/cgroup/exercise_group. Type: +2. Тепер перелічіть файли та каталоги в структурі /sys/fs/cgroup/exercise_group. Впишіть: ```bash sudo ls /sys/fs/cgroup/exercise_group/ @@ -546,7 +546,7 @@ NUMA означає "нерівномірний доступ до пам'яті" echo 4096 | sudo tee /sys/fs/cgroup/exercise_group/memory.max ``` -2. Підтвердьте, що ліміт пам’яті встановлено. Type: +2. Підтвердьте, що ліміт пам’яті встановлено. Впишіть: ```bash cat /sys/fs/cgroup/exercise_group/memory.max @@ -554,7 +554,7 @@ NUMA означає "нерівномірний доступ до пам'яті" #### Щоб створити тестовий сценарій memory_stress -1. Створіть простий виконуваний сценарій за допомогою команди `dd`, щоб перевірити обмеження ресурсу пам’яті. Type: +1. Створіть простий виконуваний сценарій за допомогою команди `dd`, щоб перевірити обмеження ресурсу пам’яті. Впишіть: ```bash cat > ~/memory_stress.sh << EOF @@ -566,7 +566,7 @@ NUMA означає "нерівномірний доступ до пам'яті" #### Щоб запустити та додати процес/сценарій до `cgroup` пам'яті -1. Запустіть memory_stress.sh, запишіть його PID і додайте PID до group.procs. Type: +1. Запустіть memory_stress.sh, запишіть його PID і додайте PID до group.procs. Впишіть: ```bash ~/memory_stress.sh & @@ -575,13 +575,13 @@ NUMA означає "нерівномірний доступ до пам'яті" Файл /sys/fs/cgroup/exercise_group/cgroup.procs можна використовувати для додавання або перегляду PID (ідентифікаторів процесів) процесів, які є членами даної `cgroup`. Запис PID до цього файлу призначає процес сценарію ~/memory_stress.sh групі `cgroup`. -2. Попередня команда завершиться дуже швидко, тому що вона перевищила обмеження пам’яті `cgroup`. Ви можете запустити таку команду `journalctl` в іншому терміналі, щоб переглянути помилку, як вона відбувається. Type: +2. Попередня команда завершиться дуже швидко, тому що вона перевищила обмеження пам’яті `cgroup`. Ви можете запустити таку команду `journalctl` в іншому терміналі, щоб переглянути помилку, як вона відбувається. Впишіть: ```bash journalctl -xe -f | grep -i memory ``` - !!! Tip + !!! Tip "Порада" ``` Ви можете швидко скористатися командою ps, щоб перевірити приблизне використання пам'яті процесом, якщо вам відомий PID процесу, запустивши: @@ -595,7 +595,7 @@ NUMA означає "нерівномірний доступ до пам'яті" #### Щоб установити новий ліміт ресурсу ЦП -1. Обмежте використання сценарієм лише 10% ядра ЦП. Type: +1. Обмежте використання сценарієм лише 10% ядра ЦП. Впишіть: ```bash echo 10000 | sudo tee /sys/fs/cgroup/exercise_group/cpu.max @@ -603,7 +603,7 @@ NUMA означає "нерівномірний доступ до пам'яті" 10000 означає обмеження пропускної здатності ЦП. Його встановлено на 10% від загальної потужності одного ядра ЦП. -2. Переконайтеся, що встановлено обмеження ЦП. Type: +2. Переконайтеся, що встановлено обмеження ЦП. Впишіть: ```bash cat /sys/fs/cgroup/exercise_group/cpu.max @@ -611,7 +611,7 @@ NUMA означає "нерівномірний доступ до пам'яті" #### Щоб створити сценарій стрес-тесту ЦП -1. Створюйте та встановлюйте дозволи на виконання для сценарію, щоб генерувати високе використання ЦП. Type: +1. Створюйте та встановлюйте дозволи на виконання для сценарію, щоб генерувати високе використання ЦП. Впишіть: ```bash cat > ~/cpu_stress.sh << EOF @@ -650,14 +650,14 @@ NUMA означає "нерівномірний доступ до пам'яті" Основний запам'ятовуючий пристрій може бути ціллю для встановлення обмежень на ресурси введення-виведення. Пристрої зберігання даних у системах Linux мають основні та другорядні номери пристроїв, які можна використовувати для їх унікальної ідентифікації. -1. По-перше, давайте створимо набір допоміжних змінних для визначення та збереження номера пристрою для основного пристрою зберігання на сервері. Type: +1. По-перше, давайте створимо набір допоміжних змінних для визначення та збереження номера пристрою для основного пристрою зберігання на сервері. Впишіть: ```bash primary_device=$(lsblk | grep disk | awk '{print $1}' | head -n 1) primary_device_num=$(ls -l /dev/$primary_device | awk '{print $5, $6}' | sed 's/,/:/') ``` -2. Далі, відобразимо значення змінної $primary_device_num. Type: +2. Далі, відобразимо значення змінної $primary_device_num. Впишіть: ```bash echo "Primary Storage Device Number: $primary_device_num" @@ -671,14 +671,14 @@ NUMA означає "нерівномірний доступ до пам'яті" #### Щоб установити нове обмеження ресурсів введення-виведення -1. Встановіть операції вводу/виводу на 1 МБ/с для процесів читання та запису в `cgroup` групи виконання. Type: +1. Встановіть операції вводу/виводу на 1 МБ/с для процесів читання та запису в `cgroup` групи виконання. Впишіть: ```bash echo "$primary_device_num rbps=1048576 wbps=1048576" | \ sudo tee /sys/fs/cgroup/exercise_group/io.max ``` -2. Підтвердьте встановлені обмеження введення/виведення. Type: +2. Підтвердьте встановлені обмеження введення/виведення. Впишіть: ```bash cat /sys/fs/cgroup/exercise_group/io.max @@ -686,7 +686,7 @@ NUMA означає "нерівномірний доступ до пам'яті" #### Щоб створити процес стрес-тесту вводу-виводу -1. Запустіть процес `dd`, щоб створити великий файл з назвою /tmp/io_stress. Також запишіть і збережіть PID процесу dd у змінній під назвою `MYPID`. Type: +1. Запустіть процес `dd`, щоб створити великий файл з назвою /tmp/io_stress. Також запишіть і збережіть PID процесу dd у змінній під назвою `MYPID`. Впишіть: ```bash dd if=/dev/zero of=/tmp/io_stress bs=10M count=500 oflag=dsync \ @@ -695,7 +695,7 @@ NUMA означає "нерівномірний доступ до пам'яті" #### Щоб додати процес/сценарій до `cgroup` вводу/виводу -1. Додайте PID попереднього процесу dd до елемента керування exercise_group `cgroup`. Type: +1. Додайте PID попереднього процесу dd до елемента керування exercise_group `cgroup`. Впишіть: ```bash echo $MYPID | sudo tee /sys/fs/cgroup/exercise_group/cgroup.procs @@ -709,11 +709,11 @@ NUMA означає "нерівномірний доступ до пам'яті" iotop -p $MYPID ``` -The output will display I/O read/write speeds for the io_stress.sh process, which should not exceed 1 MB/s as per the limit. +На виході буде відображено швидкість читання/запису вводу-виводу для процесу io_stress.sh, яка не повинна перевищувати 1 МБ/с відповідно до обмеження. -#### To remove `cgroups` +#### Щоб видалити `cgroups` -1. Type the following commands to end any background process, delete the no-longer-needed `cgroup` and remove the /tmp/io_stress file. +1. Введіть наступні команди, щоб завершити будь-який фоновий процес, видалити непотрібну `cgroup` і видалити файл /tmp/io_stress. ```bash kill %1 @@ -721,131 +721,131 @@ The output will display I/O read/write speeds for the io_stress.sh process, whic sudo rm -rf /tmp/io_stress ``` -## Exercise 8 +## Завдання 8 ### `taskset` -CPU affinity binds specific processes or threads to particular CPU cores in a multi-core system. This exercise demonstrates the use of `taskset` to set or retrieve the CPU affinity of a process in Linux. +CPU affinity прив’язує конкретні процеси або потоки до певних ядер ЦП у багатоядерній системі. Ця вправа демонструє використання `taskset` для встановлення або отримання спорідненості ЦП процесу в Linux. -### To explore CPU Affinity with `taskset` +### Щоб дослідити CPU Affinity з `taskset` -1. Use the `lscpu` to list available CPUs on your system. Type: +1. Використовуйте `lscpu`, щоб отримати список доступних ЦП у вашій системі. Впишіть: ```bash lscpu | grep "On-line" ``` -2. Давайте створимо зразок процесу за допомогою утиліти dd і збережемо його PID у змінній MYPID. Type: +2. Давайте створимо зразок процесу за допомогою утиліти dd і збережемо його PID у змінній MYPID. Впишіть: ```bash dd if=/dev/zero of=/dev/null & export MYPID="$!" echo $MYPID ``` -3. Retrieve current affinity for the `dd` process. Type: +3. Отримайте поточну спорідненість для процесу `dd`. Впишіть: ```bash taskset -p $MYPID ``` - OUTPUT: + Вихід: ```bash pid 1211483's current affinity mask: f ``` - Вихідні дані показують маску спорідненості ЦП процесу з PID 1211483 ($MYPID), представленим у шістнадцятковому форматі. On our sample system, the affinity mask displayed is "f", which typically means that the process can run on any CPU core. + Вихідні дані показують маску спорідненості ЦП процесу з PID 1211483 ($MYPID), представленим у шістнадцятковому форматі. У нашому прикладі системи відображається маска спорідненості «f», що зазвичай означає, що процес може виконуватися на будь-якому ядрі ЦП. !!! note - The CPU affinity mask "f" represents a configuration where all CPU cores are enabled. In hexadecimal notation, "f" corresponds to the binary value "1111". Each bit in the binary representation corresponds to a CPU core, with "1" indicating that the core is enabled and available for the process to run on. + Маска спорідненості ЦП "f" представляє конфігурацію, у якій увімкнено всі ядра ЦП. У шістнадцятковій системі числення «f» відповідає двійковому значенню «1111». Кожен біт у двійковому представленні відповідає ядру ЦП, причому «1» означає, що ядро ввімкнено та доступне для виконання процесу. - Therefore, on four core CPU, with the mask "f": + Тому на чотириядерному процесорі з маскою "f": Core 0: Enabled Core 1: Enabled Core 2: Enabled Core 3: Enabled -### To set/change CPU affinity +### Щоб встановити/змінити схожість ЦП -1. Встановіть приналежність ЦП процесу dd до одного ЦП (ЦП 0). Type: +1. Встановіть приналежність ЦП процесу dd до одного ЦП (ЦП 0). Впишіть: ```bash taskset -p 0x1 $MYPID ``` - OUTPUT + ВИХІД ```bash pid 1211483's current affinity mask: f pid 1211483's new affinity mask: 1 ``` -2. Verify the change by running the following: +2. Перевірте зміни, виконавши: ```bash taskset -p $MYPID ``` - Вихідні дані вказують на маску спорідненості ЦП процесу з PID $MYPID. The affinity mask is "1" in decimal, which translates to "1" in binary. This means that the process is currently bound to CPU core 0. + Вихідні дані вказують на маску спорідненості ЦП процесу з PID $MYPID. Маска спорідненості дорівнює «1» у десятковій системі, що перекладається як «1» у двійковій системі. Це означає, що процес наразі прив’язаний до ядра ЦП 0. -3. Тепер встановіть приналежність ЦП процесу dd до кількох ЦП (ЦП 0 і 1). Type: +3. Тепер встановіть приналежність ЦП процесу dd до кількох ЦП (ЦП 0 і 1). Впишіть: ```bash taskset -p 0x3 $MYPID ``` -4. Issue the correct `tasksel` command to verify the latest change. +4. Видайте правильну команду `tasksel`, щоб перевірити останню зміну. ```bash taskset -p $MYPID ``` - On our demo 4-core CPU server, the output shows that the CPU affinity mask of the process is "3" (in decimal). This translates to "11" in binary. + На нашому демонстраційному 4-ядерному сервері ЦП результат показує, що маска спорідненості ЦП процесу дорівнює «3» (у десятковому вигляді). Це означає «11» у двійковій системі. !!! tip - Decimal "3" is "11" (or 0011) in binary. - Each binary digit corresponds to a CPU core: core 0, core 1, core 2, core 3 (from right to left). - The digit "1" in the fourth and third positions (from the right) indicates that the process can run on cores 0 and 1. - Therefore, "3" signifies that the process is bound to CPU cores 0 and 1. + Десятковий "3" дорівнює "11" (або 0011) у двійковій системі. + Кожна двійкова цифра відповідає ядру ЦП: ядро 0, ядро 1, ядро 2, ядро 3 (справа наліво). + Цифра «1» на четвертій і третій позиціях (справа) означає, що процес може працювати на ядрах 0 і 1. + Тому «3» означає, що процес прив’язаний до ядер ЦП 0 і 1. -5. Launch either the `top` or `htop` utility in a separate terminal and observe if you see anything of interest as you experiment with different `taskset` configurations for a process. +5. Запустіть утиліту `top` або `htop` в окремому терміналі та спостерігайте, якщо ви бачите щось цікаве, експериментуючи з різними конфігураціями `taskset` для процесу. -6. All done. Використовуйте його PID ($MYPID), щоб припинити процес dd. +6. Все готово. Використовуйте його PID ($MYPID), щоб припинити процес dd. -## Exercise 9 +## Завдання 9 ### `systemd-run` -The `systemd-run` command creates and starts transient service units for running commands or processes. It can also run programs in transient scope units, path-, socket-, or timer-triggered service units. +Команда `systemd-run` створює та запускає тимчасові службові блоки для виконання команд або процесів. Він також може запускати програми в одиницях тимчасового обсягу, одиницях обслуговування, що запускаються за допомогою шляху, сокета або таймера. -This exercise shows how to use `systemd-run` for creating transient service units in `systemd`. +У цій вправі показано, як використовувати `systemd-run` для створення тимчасових службових одиниць у `systemd`. -#### To run a command as a transient service +#### Щоб запустити команду як тимчасову службу -1. Run the simple sleep 300 command as a transient `systemd` service using `systemd-run`. Type: +1. Запустіть просту команду sleep 300 як тимчасову службу `systemd` за допомогою `systemd-run`. Впишіть: ```bash systemd-run --unit=mytransient.service --description="Example Service" sleep 300 ``` -2. Check the status of the transient service using `systemctl status`. Type: +2. Перевірте статус тимчасової служби за допомогою `systemctl status`. Впишіть: ```bash systemctl status mytransient.service ``` -#### To set a memory resource limit for a transient service +#### Щоб установити обмеження ресурсу пам’яті для тимчасової служби -1. Use the `--property` parameter with `systemd-run` to limit the maximum memory usage for the transient process to 200M. Type: +1. Використовуйте параметр `--property` разом із `systemd-run`, щоб обмежити максимальне використання пам’яті для тимчасового процесу до 200 Мб. Впишіть: ```bash systemd-run --unit=mylimited.service --property=MemoryMax=200M sleep 300 ``` -2. Look under the corresponding `cgroup` file system for the process to verify the setting. Type: +2. Подивіться у відповідній файловій системі `cgroup` процес перевірки налаштування. Впишіть: ```bash sudo cat /sys/fs/cgroup/system.slice/mytransient.service/memory.max @@ -855,22 +855,22 @@ This exercise shows how to use `systemd-run` for creating transient service unit `systemd.resource-control` — це конфігурація або керуюча сутність (концепція) у рамках `systemd`, призначена для керування та розподілу системних ресурсів для процесів і служб. А `systemd.exec` — це компонент `systemd`, який відповідає за визначення середовища виконання, у якому виконуються команди. Щоб переглянути різні параметри (властивості), які ви можете налаштувати під час використання systemd-run, зверніться до сторінок посібника `systemd.resource-control` і `systemd.exec`. Тут ви знайдете документацію для таких властивостей, як MemoryMax, CPUAccounting, IOWeight тощо. -#### To set CPU resource limit for a transient service +#### Щоб установити обмеження на ресурс ЦП для тимчасової служби -1. Давайте створимо тимчасовий блок `systemd` під назвою "myrealtime.service". Запустіть myrealtime.service із спеціальною політикою планування циклічного (rr) і пріоритетом. Type: +1. Давайте створимо тимчасовий блок `systemd` під назвою "myrealtime.service". Запустіть myrealtime.service із спеціальною політикою планування циклічного (rr) і пріоритетом. Впишіть: ```bash systemd-run --unit=myrealtime.service \ --property=CPUSchedulingPolicy=rr --property=CPUSchedulingPriority=50 sleep 300 ``` -2. Перегляньте статус myrealtime.service. Also, capture/store the main [sleep] PID in a MYPID variable. Type: +2. Перегляньте статус myrealtime.service. Крім того, захопіть/збережіть основний [sleep] PID у змінній під назвою MYPID. Впишіть: ```bash MYPID=$(systemctl status myrealtime.service | awk '/Main PID/ {print $3}') ``` -3. Verify its CPU scheduling policy While the service is still running. Type: +3. Поки служба все ще працює, перевірте її політику планування ЦП. Впишіть: ```bash chrt -p $MYPID @@ -878,26 +878,26 @@ This exercise shows how to use `systemd-run` for creating transient service unit pid 2553792's current scheduling priority: 50 ``` -### To create a transient timer unit +### Щоб створити блок перехідного часу -1. Create a simple timer unit that runs a simple echo command. The `--on-active=2m` option sets the timer to trigger 2 minutes after the timer unit becomes active. Type: +1. Створіть простий таймер, який виконує просту команду echo. Параметр `--on-active=2m` встановлює таймер на спрацьовування через 2 хвилини після того, як блок таймера стане активним. Впишіть: ```bash systemd-run --on-active=2m --unit=mytimer.timer \ --description="Example Timer" echo "Timer triggered" ``` - The timer will start counting down from the time the unit is activated, and after 2 minutes, it will trigger the specified action. + Таймер почне відлік часу з моменту активації пристрою і через 2 хвилини запустить вказану дію. -2. View details/status for the timer unit that was just created. Type: +2. Переглянути деталі/статус щойно створеного таймера. Впишіть: ```bash systemctl status mytimer.timer ``` -#### To stop and clean up transient `systemd` units +#### Щоб зупинити та очистити тимчасові блоки `systemd` -1. Type the following commands to ensure that the various transient services/processes started for this exercise are properly stopped and removed from your system. Type: +1. Введіть наступні команди, щоб переконатися, що різні тимчасові служби/процеси, запущені для цієї вправи, належним чином зупинені та видалені з вашої системи. Впишіть: ```bash systemctl stop mytransient.service @@ -906,23 +906,23 @@ This exercise shows how to use `systemd-run` for creating transient service unit systemctl stop mytimer.timer ``` -## Exercise 10 +## Вправа 10 ### `schedtool` -This exercise demonstrates the use of `schedtool` to understand and manipulate process scheduling in Rocky Linux. Ми також створимо сценарій для моделювання процесу для цієї мети. +Ця вправа демонструє використання `schedtool` для розуміння та керування плануванням процесів у Rocky Linux. Ми також створимо сценарій для моделювання процесу для цієї мети. -#### To install `schedtool` +#### Щоб встановити `schedtool` -1. Install the `schedtool` application if it is not installed on your server. Type: +1. Встановіть програму `schedtool`, якщо вона не встановлена на вашому сервері. Впишіть: ```bash sudo dnf -y install schedtool ``` -#### To create a simulated process script +#### Щоб створити імітований сценарій процесу -1. Create a script that generates CPU load for testing purposes. Type: +1. Створіть сценарій, який генерує навантаження на процесор для цілей тестування. Впишіть: ```bash cat > ~/cpu_load_generator.sh << EOF @@ -936,75 +936,75 @@ This exercise demonstrates the use of `schedtool` to understand and manipulate p chmod +x ~/cpu_load_generator.sh ``` -2. Start the script in the background. Type: +2. Запустіть сценарій у фоновому режимі. Впишіть: ```bash ~/cpu_load_generator.sh & echo $! ``` -3. Зберіть PID для основного процесу `openssl`, запущеного в сценарії cpu_load_generator.sh. Зберігайте PID у змінній з іменем MYPID. Type: +3. Зберіть PID для основного процесу `openssl`, запущеного в сценарії cpu_load_generator.sh. Зберігайте PID у змінній з іменем MYPID. Впишіть: ```bash export MYPID=$(pidof openssl) ; echo $MYPID ``` -#### To use `schedtool` to check the current scheduling policy +#### Щоб використовувати `schedtool` для перевірки поточної політики планування -1. Використовуйте команду `schedtool`, щоб відобразити інформацію про планування процесу з PID $MYPID. Type: +1. Використовуйте команду `schedtool`, щоб відобразити інформацію про планування процесу з PID $MYPID. Впишіть: ```bash schedtool $MYPID ``` - OUTPUT: + Вихід: ```bash PID 2565081: PRIO 0, POLICY N: SCHED_NORMAL , NICE 0, AFFINITY 0xf ``` -#### To use `schedtool` to modify the scheduling policy +#### Щоб використовувати `schedtool` для зміни політики планування -1. Change the scheduling policy and priority of the process FIFO and 10, respectively. Type: +1. Змініть політику планування та пріоритет процесу FIFO та 10 відповідно. Впишіть: ```bash sudo schedtool -F -p 10 $! ``` -2. View the effect of the changes. Type: +2. Перегляньте ефект від змін. Впишіть: ```bash schedtool $MYPID ``` -3. Change the scheduling policy and priority of the process to round robin or SCHED_RR (RR) and 50, respectively. Type: +3. Змініть політику планування та пріоритет процесу на циклічний або SCHED_RR (RR) і 50 відповідно. Впишіть: ```bash sudo schedtool -R -p 50 $MYPID ``` -4. View the effect of the changes. Type: +4. Перегляньте ефект від змін. Впишіть: ```bash schedtool $MYPID ``` -5. Change the scheduling policy of the process to Idle or SCHED_IDLEPRIO (D). Type: +5. Змініть політику планування процесу на Idle або SCHED_IDLEPRIO (D). Впишіть: ```bash sudo schedtool -D $MYPID ``` -6. View the effect of the changes. +6. Перегляньте ефект від змін. -7. Finally, reset the scheduling policy of the process back to the original default SCHED_NORMAL (N or other). Type: +7. Нарешті, скиньте політику планування процесу назад до початкового стандартного SCHED_NORMAL (N або інше). Впишіть: ```bash sudo schedtool -N $MYPID ``` -#### To terminate and clean up the `cpu_load_generator.sh` process +#### Щоб завершити та очистити процес `cpu_load_generator.sh` -1. All done. Terminate the script and delete the `cpu_load_generator.sh` script. +1. Все готово. Завершіть сценарій і видаліть сценарій `cpu_load_generator.sh`. ```bash kill $MYPID diff --git a/docs/rocky_insights/blogs/good_docs.it.md b/docs/rocky_insights/blogs/good_docs.it.md new file mode 100644 index 0000000000..e056bf9d1f --- /dev/null +++ b/docs/rocky_insights/blogs/good_docs.it.md @@ -0,0 +1,88 @@ +--- +title: Good Docs - Il punto di vista di un traduttore +author: Ganna Zhyrnova +contributors: Steven Spencer +--- + +## Introduzione + +I traduttori forniscono indicazioni preziose per la stesura di una documentazione chiara e concisa. Sanno cosa non si traduce bene e cosa confonde il lettore meglio di chiunque altro. Questo documento esamina alcuni di questi aspetti ed evidenzia le migliori pratiche per la stesura dei documenti. + +### Dall'autore + +La documentazione del software aiuta gli utenti a capire come utilizzare efficacemente un determinato software. Devono capire cosa otterranno alla fine e quali vantaggi avranno. Allo stesso tempo, quando create una documentazione, significa crearla non solo per voi stessi, ma anche per la vostra rete e per le altre persone che potrebbero leggerla. Gli altri utenti potrebbero non provenire da paesi anglofoni. Ciò significa che per loro l'inglese non è la lingua principale. Proprio per questo motivo, seguite queste regole di base per rendere la documentazione più leggibile a _tutti_ gli utenti. + +## Uso di un linguaggio semplice + +In linea di principio, non si ha idea di chi siano i fruitori della documentazione. Se l'utente abbia o meno familiarità con questo ambito, che sia uno sviluppatore esperto o un principiante. Un linguaggio semplice sta a significare una comunicazione chiara, concisa e di facile comprensione per il pubblico a cui è destinata la prima volta che la incontra. E' da evitare i termini gergali, quelli troppo tecnici e frasi con strutture complesse, a favore di un linguaggio più semplice e con un'organizzazione chiara. L'obiettivo è garantire che il messaggio sia accessibile e comprensibile a un ampio pubblico, indipendentemente dal suo background o dal suo livello di lettura. Spesso è possibile farlo semplificando la sintassi delle frase o i comandi fino ad una forma più elementare. + +## Evitare espressioni idiomatiche, gergo, acronimi e contrazioni. + +Idiomi, gergo, contrazioni e acronimi possono confondere i lettori che non li conoscono, in particolare coloro che non sono madrelingua, i nuovi dipendenti o tutti coloro che estranei al vostro settore specifico. + +I **diomi** sono spesso culturalmente specifici e possono essere difficili da capire per i lettori internazionali.\ +Il **gergo** comprende termini specialistici che solo gli esperti di un settore possono riconoscere.\ +Le **contrazioni** sostituiscono le parole della lingua inglese con scorciatoie, che però non sempre esistono in tutte le lingue, rendendo difficile la traduzione.\ +Gli **acronimi** possono essere ambigui, soprattutto se non vengono definiti al momento del loro utilizzo. + +Esempio: + +❌ “Una volta presa confidenza con il cruscotto, il resto è un gioco da ragazzi”. In questo caso, l'autore utilizza sia una contrazione, sia uno slang, sia un idioma. + +✅ “Una volta imparato a usare il cruscotto, il resto è facile”. Sostituendo la contrazione, il gergo e l'idioma con le parole associate a ciascuno di essi, il significato è chiaro. + +Il linguaggio figurato, come i modi di dire, spesso non si traduce bene. I redattori tecnici o i traduttori potrebbero avere difficoltà a trasmettere lo stesso significato in altre lingue. + +Esempio: + +❌ “Ci sentiamo la prossima settimana per fare il punto sui ticket aperti”. + +✅ “Incontriamoci la prossima settimana per rivedere le richieste di supporto non risolte”. + +Il gergo e gli acronimi possono generare confusione, anche all'interno della stessa organizzazione, se il loro significato non è universalmente conosciuto. + +Esempio: + +❌ “Caricare il CSV nel CMS ed etichettarlo secondo le SOP”. + +✅ “Caricare il file CSV (Comma-Separated Values) nel Content Management System (CMS) ed etichettarlo secondo le procedure operative standard (SOP).” + +Nota: se si desidera utilizzare acronimi, definirli sempre la prima volta: “Content Management System (CRM)”. + +Eliminando i modi di dire e il gergo non necessario, il significato del documento diventa più chiaro. Sostituire le contrazioni con le parole che rappresentano significa facilitare gli sforzi di traduzione in tutte le lingue. Il documento è più comprensibile per il lettore quando si sostituiscono o si definiscono gli acronimi. + +## Uso della forma attiva + +La voce attiva enfatizza chi compie l'azione, rendendo chiaro chi o cosa è responsabile dell'azione del verbo. + +Esempio: + +Il sistema apre la finestra di dialogo in cui è necessario completare il modulo. + +Si prega di astenersi dall'utilizzare una forma complessa, in quanto può confondere i lettori. + +Per saperne di più sull'uso della forma attiva e sulla sua importanza, si veda [questa parere](active_voice.md) e [questa fonte esterna](https://developers.google.com/tech-writing/one/active-voice). + +## Dividere in step + +Se la documentazione contiene passaggi specifici, separateli l'uno dall'altro. + +Ad esempio: + +Passo 1 - Accedere alla sezione +Passo 2 - Fare clic sul pulsante +Passo 3 - Compilare il modulo +...\ +Passo N - salvare le modifiche + +## Screenshot quando necessario + +Utilizzate screenshot corretti dove necessario. Ciò significa che non è necessario aggiungere screenshot ovunque, ma solo nei punti in cui è necessario fornire ulteriori spiegazioni. + +## Uso degli esempi + +Se è necessario compilare il modulo, fornire esempi di come gli utenti possono completarlo. Indicare le limitazioni, se ci sono. + +## Conclusione + +Scrivere una buona documentazione non significa solo renderla tecnicamente accurata, ma anche renderla immediatamente comprensibile al lettore. Questo è particolarmente importante quando un documento tecnico deve essere tradotto in altre lingue. In questo documento, l'autore intendeva mettere in evidenza le tecniche specifiche per scrivere una buona documentazione chiara. diff --git a/docs/rocky_insights/blogs/good_docs.uk.md b/docs/rocky_insights/blogs/good_docs.uk.md new file mode 100644 index 0000000000..b362d9e2b8 --- /dev/null +++ b/docs/rocky_insights/blogs/good_docs.uk.md @@ -0,0 +1,88 @@ +--- +title: Хороший документ — точка зору перекладача +author: Ganna Zhyrnova +contributors: Steven Spencer +--- + +## Вступ + +Перекладачі надають цінні поради щодо написання чіткої та лаконічної документації. Вони краще за інших знають, що не перекладається добре і що заплутує читача. У цьому документі розглядаються деякі з цих питань та висвітлюються найкращі практики створення документів. + +### Від автора + +Документація до програмного забезпечення допомагає користувачам зрозуміти, як ефективно використовувати конкретне програмне забезпечення. Вони повинні розуміти, що вони отримають в результаті і які переваги це їм дасть. Водночас, коли ви створюєте документацію, це означає, що ви створюєте її не тільки для себе, але й для своєї мережі та інших людей, які можуть її прочитати. Інші люди можуть бути не з англомовних країн. Це означає, що для них англійська мова не є основною мовою. З огляду на це, дотримуйтесь цих основних правил, щоб зробити вашу документацію більш зрозумілою для _всіх_ користувачів. + +## Використання простої мови + +Ви не маєте уявлення, хто є вашим користувачем. Незалежно від того, чи знайомий цей користувач з цією сферою, чи є він досвідченим розробником або початківцем. Проста мова — це чітка, лаконічна комунікація, яку цільова аудиторія може легко зрозуміти з першого разу. Вона уникає жаргон, технічні терміни та складні синтаксичні конструкції на користь простішої мови та чіткої структури. Мета полягає в тому, щоб забезпечити доступність і зрозумілість повідомлення для широкої аудиторії, незалежно від її походження або рівня читацької підготовки. Часто це можна зробити, спростивши структуру речень або команд до їх найпростішого формату. + +## Уникайте ідіом, жаргону, акронімів та скорочень + +Ідіоми, жаргон, скорочення та акроніми можуть заплутати читачів, які не знайомі з ними, особливо тих, хто не є носіями мови, нових співробітників або людей, які не належать до вашої конкретної галузі. + +**Ідіоми** часто мають культурну специфіку і можуть бути важкими для розуміння міжнародним читачам.\ +**Жаргон** включає спеціалізовані терміни, які можуть розуміти лише експерти в певній галузі.\ +**Скорочення** замінюють слова в англійській мові скороченими формами, але такі скорочення не завжди існують у всіх мовах, що ускладнює переклад.\ +**Акроніми** можуть бути неоднозначними, особливо якщо вони не визначені при першому використанні. + +Приклад: + +❌ "Once you’ve got the hang of the dashboard, the rest is a piece of cake." Тут автор використовує скорочення, сленг та ідіому. + +✅ "Once you have learned how to use the dashboard, the rest is easy." Замінивши скорочення, сленг та ідіоми словами, пов'язаними з кожним з них, значення стає зрозумілим. + +Фігуративні вирази, такі як ідіоми, часто важко перекласти. Технічні письменники або перекладачі можуть зіткнутися з труднощами при передачі того самого значення іншими мовами. + +Приклад: + +❌ "Let’s touch base next week to circle back on the open tickets." + +✅ "Let us meet next week to review the unresolved support requests." + +Жаргонні слова та абревіатури можуть викликати плутанину — навіть у межах однієї організації — якщо їх значення не є загальновідомими. + +Приклад: + +❌ "Upload the CSV to the CMS and tag it according to SOPs." + +✅ "Upload the CSV (Comma-Separated Values file) to the content management system and label it according to the standard operating procedures." + +Примітка: Якщо ви хочете використовувати акроніми, завжди визначайте їх при першому використанні: «Система управління взаємовідносинами з клієнтами (CRM)». + +Вилучивши ідіоми та непотрібний жаргон, ви зробите зміст вашого документа більш зрозумілим. Заміна скорочень словами, які вони позначають, означає, що переклад на всі мови стає простішим. Ваш документ буде найбільш зрозумілим для читача, якщо ви заміните або поясните абревіатури. + +## Використовуйте Active Voice + +Active voice підкреслює виконавця дії, даючи зрозуміти, хто або що є відповідальним за дію дієслова. + +Приклад: + +The system opens the dialog where you need to complete the form. + +Будь ласка, утримайтеся від використання складної форми, оскільки вона може заплутати читачів. + +Більше інформації про використання активного голосу та важливість його використання див. [цю думку](active_voice.md) та [це зовнішнє джерело](https://developers.google.com/tech-writing/one/active-voice). + +## Опис кроків + +Якщо у документації є конкретні кроки, розділіть їх один від одного. + +Наприклад: + +Step 1 - Go to the section\ +Step 2 - Click the button\ +Step 3 - Complete the form\ +...\ +Step N - save changes + +## Додавайте скріншоти де необхідно + +Використовуйте правильні знімки екрана, де це необхідно. Це означає, що вам не потрібно додавати скріншоти всюди, а лише в тих місцях, де потрібні додаткові пояснення. + +## Використовуйте приклади + +Якщо потрібно заповнити форму, наведіть приклади того, як користувачі можуть її заповнити. Вкажіть обмеження, якщо вони є. + +## Висновок + +Написання хорошої документації – це не тільки забезпечення її технічної точності, але й дуже важливо зробити її зрозумілою для читача з першого погляду. Це особливо важливо, коли технічний документ потрібно перекласти на інші мови. У цьому документі автор мав на меті висвітлити конкретні техніки написання якісної та зрозумілої документації. diff --git a/docs/rocky_insights/blogs/good_docs.zh.md b/docs/rocky_insights/blogs/good_docs.zh.md new file mode 100644 index 0000000000..9c7e29d2c3 --- /dev/null +++ b/docs/rocky_insights/blogs/good_docs.zh.md @@ -0,0 +1,88 @@ +--- +title: 优质文档规范——译者视角 +author: Ganna Zhyrnova +contributors: Steven Spencer +--- + +## 介绍 + +译者能为撰写清晰简明的文档提供宝贵洞见。 他们比大多数人更清楚哪些内容难以准确翻译、哪些表述容易引发读者困惑。 本文剖析了此类典型问题，并聚焦优质文档创作的最佳实践指南。 + +### 来自作者 + +软件文档帮助用户理解如何高效使用特定软件。 用户需要明确了解最终能实现什么成果以及获得哪些收益。 同时，在创建文档时应当意识到，您不仅是为自己编写，更是为技术社群及其他可能阅读的人而写作。 其他人可能不是来自英语国家。 这意味着对他们来说，英语不是他们的主要语言。 因此，遵循这些基本规则，使您的文档对 _所有_ 用户都更具可读性。 + +## 使用通俗易懂的语言 + +您根本不知道您的用户是谁。 无论这个用户是否熟悉这个领域，无论他们是经验丰富的开发者还是初学者。 通俗易懂的语言是清晰、简洁且能让目标受众在初次接触时就能理解的交流方式。 应避免使用行话、技术术语和复杂的句子结构，而应该倾向于使用更简单的语言和清晰的组织方式。 其目标是确保信息对广泛的受众来说都是可获取且易于理解的，无论他们的背景或阅读水平如何。 通常，您可以通过将句子结构或命令简化到最基本的格式来做到这一点。 + +## 避免使用习语、术语、首字母缩略词和缩略形式 + +习语、术语、缩略形式和首字母缩略词可能会让不熟悉它们的读者感到困惑，尤其是非母语人士、新员工或特定领域之外的人。 + +**习语** 通常具有文化特殊性，对于国际读者来说很难理解。\ +**术语** 涉及只有某一领域的专家才能识别的专业术语。\ +**缩略形式** 在英语中用简化形式替代完整词汇，但并非所有语言都存在类似用法，导致翻译困难。\ +**首字母缩略词** 易产生歧义，尤其是在首次使用时没有定义的情况下。 + +示例： + +❌ "Once you’ve got the hang of the dashboard, the rest is a piece of cake." 在这里，作者使用了缩略形式、俚语和习语。 + +✅ "Once you have learned how to use the dashboard, the rest is easy." 通过将缩略形式、俚语和习语替换为与之相关的词语，意思就清晰了。 + +诸如习语之类的比喻性语言通常难以翻译。 技术作者或翻译人员可能很难在其他语言中传达相同的意思。 + +示例： + +❌ "Let’s touch base next week to circle back on the open tickets." + +✅ "Let us meet next week to review the unresolved support requests." + +术语和首字母缩略词若未被普遍知晓，即使在同一个组织内部也可能造成混淆。 + +示例： + +❌ "Upload the CSV to the CMS and tag it according to SOPs." + +✅ "Upload the CSV (Comma-Separated Values file) to the content management system and label it according to the standard operating procedures." + +注意：如果你想使用首字母缩略词，请务必在第一次定义它们："Customer Relationship Management (CRM) system"。 + +通过消除习语和不必要的术语，文档的含义会变得更加清晰。 将缩略形式替换为其代表的完整词语，意味着所有语言的翻译工作都会变得更容易。 当您替换或定义首字母缩略词时，您的文档对读者来说是最易理解的。 + +## 使用主动语态 + +主动语态强调动作的执行者，明确指出谁或什么对动词所表示的动作负责。 + +示例： + +The system opens the dialog where you need to complete the form. + +请避免使用复数形式，因为它会让读者感到困惑。 + +有关主动语态的使用以及使用它的意义，请参阅 [此观点](active_voice.md) 和 [此外部来源](https://developers.google.com/tech-writing/one/active-voice)。 + +## 具体步骤 + +如果文档中有特定的步骤，请将它们分开。 + +例如： + +Step 1 - Go to the section\ +Step 2 - Click the button\ +Step 3 - Complete the form\ +...\ +Step N - save changes + +## 必要时进行截图 + +在需要的地方使用正确的截图。 这意味着您无需到处添加截图，仅在需要进一步解释的地方添加即可。 + +## 使用示例 + +如果你需要填写表格，那么请提供用户如何填写的示例。 如果有任何限制，请一并说明。 + +## 总结 + +编写好的文档，不仅要确保其技术上的准确性，还要让读者能够立刻理解。 这一点在技术文档需要翻译成其他语言时尤为重要。 在这份文档中，作者旨在强调编写优质、清晰文档的特定技巧。