Базова стратегія підтримки документації двома мовами

Документ є базовим баченням майбутньої стратегії підтримки Antora-документації двома мовами.

1. Першоджерело для створення та підтримки документації

  • Українська версія документації (ua) є source of truth.

  • Англійська версія документації (en) є другорядною, для перекладу.

2. Зони відповідальності

Архітектурний розділ (arch)

  • За розробку та підтримку архітектурних сторінок відповідає архітектурна команда (SA Team). В окремих випадках — технічний письменник (TW).

  • Переклад англійською виконує окремий перекладач (TW/BA) автономно.

Документація для користувачів (ROOT, admin, registry-develop, platform-develop, user, release-notes, faq)

  • За розробку та підтримку користувацьких сторінок відповідає технічний письменник (TW). В окремих випадках — архітектурна команда (SA Team).

  • Переклад англійською виконує окремий перекладач (TW/BA) автономно.

Тестування атрибутів якості (testing)

  • За розробку та підтримку сторінок тестування атрибутів якості відповідає команда тестувальників (QA) або розробники за участі технічного письменника (TW). В окремих випадках — архітектурна команда (SA Team).

Глосарій Платформи

  • За підтримку глосарія українською мовою відповідає технічний письменник. В окремих випадках — архітектурна команда (SA Team).

  • Переклад глосарія на англійську виконує окремий перекладач (TW/BA) автономно.

3. Передумови

  1. Найголовніше — знати, що у певній версії документації (/ua або /en), у певному файлі щось змінилося: де змінилося, коли змінилося та ким.

  2. Усі представники команди мають чітко розуміти, що у нас двомовна документація.

  3. Коли хтось створює новий файл, він має чітко розуміти, що такий самий файл потрібно мати й іншою мовою.

  4. Коли хтось вносить зміни до файлу UA-версії, він має чітко розуміти, що такі ж зміни потрібно внести й іншою мовою.

  5. Коли хтось робить файл deprecated, то такий файл треба зробити deprecated й іншою мовою.

  6. Коли хтось видаляє файл, то такий файл потрібно видалити й в іншій версії.

Потрібно чітко розуміти специфіку UA та EN документації. Деякі UA specific файли можуть бути не потрібними в UA-версії, або адаптовані з відповідною позначкою (як приклад — UA specific), і навпаки – деякі EN-файли можуть бути непотрібними в UA.

4. Процес

4.1. Ініціалізація та структуризація

  • Має бути дзеркальна структура для ua та en версій у різних папках.

  • Імена файлів мають відповідати один одному.

4.2. Виявлення змін

  • Використання diff для порівняння версій, а також інших аналогічних інструментів.

    Приклад використання git diff у терміналі для файлу index.adoc
    git diff HEAD:docs/ua/modules/ROOT/pages/index.adoc docs/en/modules/ROOT/pages/index.adoc

  • Можливість використання різних терміналів для цього процесу.

    Наприклад:

    Intellij IDEA, схоже, не вміє візуалізувати команди git diff із терміналу у вигляді посилань, які можна натиснути та відкрити у вікні редактора та переглянути зміни до файлу. Схоже, це вміє робити термінал у VS Code — необхідно перевірити це.

4.3. Автоматизація

  • Використання Git-хуків для автоматичного порівняння змін та нотифікації.

  • Використання окремого каналу в Teams тощо.

Взяти до уваги потенційну проблему спаму через велику кількість повідомлень.

4.4. Вказівки про доступність мов

Сторінки, доступні двома мовами, повинні мати відповідну примітку на початку документа.

4.5. Ревізія та оновлення

  • Щоденний перегляд git log для відстежування змін.

  • Періодичне порівняння всіх файлів, зокрема з використанням diff або інших інструментів.

  • Одразу перекладати зміни, якщо такі виявлено.

  • Якщо це новий документ, то він має бути відмічений як такий, що у «У процесі формування» тощо, щоб не перекладати те, що завтра 10 разів зміниться:

    • Визначити статуси написання з SME.

    • Створити задачу та взяти в роботу, коли можна буде перекладати.

  • Відмічати у повідомленні до коміту явно: "no translation". Лише такі коміти брати в роботу.

4.6. Документація та навчання

У файлі README пояснити процес роботи із двома мовами. Це забезпечить узгодженість у команді.

4.7. Одна візуалізація на один файл

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