Хороший документ — точка зору перекладача

Вступ

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

Від автора

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

Використання простої мови

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

Уникайте ідіом, жаргону, акронімів та скорочень

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

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

Приклад:

❌ "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.

Будь ласка, утримайтеся від використання складної форми, оскільки вона може заплутати читачів.

Більше інформації про використання активного голосу та важливість його використання див. цю думку та це зовнішнє джерело.

Опис кроків

Якщо у документації є конкретні кроки, розділіть їх один від одного.

Наприклад:

Step 1 - Go to the section\ Step 2 - Click the button\ Step 3 - Complete the form\ ...\ Step N - save changes

Додавайте скріншоти де необхідно

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

Використовуйте приклади

Якщо потрібно заповнити форму, наведіть приклади того, як користувачі можуть її заповнити. Вкажіть обмеження, якщо вони є.

Висновок

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

Author: Ganna Zhyrnova

Contributors: Steven Spencer