Англійська для розробників Docusaurus

Docusaurus, створений командою відкритого коду Meta, є типовим вибором для багатьох команд, що створюють версію документації продукту з можливістю пошуку. Оскільки сайти документації мають свої власні проблеми — версії, бічні панелі, перегляд документів як коду — словник навколо Docusaurus змішує терміни React / MDX з документацією. Цей підручник містить інформацію, яка вам знадобиться під час написання документації, перегляду PR документації або пояснення структури сайту новому технічному автору.

---

Коди-фундаменти

Docs-as-code — документація, як і початковий код: написана у вигляді звичайних текстових файлів, з контролем версій, і переглядається за допомогою запитів на витягування, а не окремого потоку роботи CMS.

• “Оскільки ми є докс-як-код, виправлення документації проходить через той же процес перегляду PR, що і інженерна зміна.” *

** MDX ** — markdown, який підтримує вбудовування компонентів React безпосередньо всередині вмісту, що дозволяє поєднувати прозу з інтерактивними елементами, такими як вкладки або приклади коду.

• “Ми використовували компонент MDX для додавання живого, запускаемого пісочниці коду безпосередньо у середині початкового довідника, замість статичного блоку коду.” *

** Front matter ** — блок метаданих YAML у верхній частині файла doc, який визначає його заголовок, розташування бічної панелі і інші параметри на рівні сторінки.

“Встановлення sidebar_position: 2 на передній панелі — це спосіб керування порядком, без підтримки окремих налаштувань бічної панелі для кожної сторінки.”

---

Versioning

Версії документів

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

“Клієнт на v2 був збентежений документацією, яка описує функцію тільки v3 — це саме той вид невідповідності, якому має запобігати версування документації.”

Версія Snapshot

** Знімок версії ** заморожує поточний стан вашої теки docs у версійну копію під час вирізання нового випуску, отже майбутні зміни до docs впливатимуть лише на « наступну » (не випущену) версію.

“Коли ми вирізали v3, ми зробили знімок версії документації — відтепер тільки навмисні зворотні порти торкаються знімка v2.”

Наступна / Невипущена версія

** наступна ** версія (іноді з позначкою « не випущена ») містить документацію для можливостей, які ще не були випущені, і зберігається окремо від поточної стабільної версії.

“Ми написали документацію нового API для наступної версії, тому вони не з’ являться для користувачів стабільної версії доки випуск не буде дійсно випущений.”

---

Структура сайту

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

• “Ми перейшли з автоматично створеної бічної панелі на явну, коли структура тек перестала відповідати порядку, за яким ми хотіли, щоб читачі стежили.” *

** Додаток ** — розширення Docusaurus, яке додає функціональність, яка не передбачена основними налаштуваннями docs/ blog — інтеграцію пошуку, сторінку журналу змін або нетипові джерела даних.

“Ми додали додаток, який витягує специфікацію OpenAPI і автоматично створює повністю інтерактивну сторінку довідки API.”

** Попередні налаштування ** — набір додатків і тем, які налаштовано разом для спільного використання (наприклад, класичні попередні налаштування, які поєднують документацію, блог і тематичний компонування).

• “Класичне налаштування дало нам документацію, блог і робочу тему — нам потрібно було лише додати один додаток для пошуку.” *

---

Перегляд та аналіз потоку роботи

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

“Ми обгорнули попередження про зміну в попередження :::danger, тому його візуально неможливо пропустити під час перегляду сторінки.”

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

“Збірка зазнала невдачі, тому що посилання вказувало на сторінку, яку ми перейменували — перевірка пошкоджених посилань виявила його, перш ніж воно дійшло до виробництва.”

** ІД документа ** — стабільний ідентифікатор сторінки документа, незалежний від шляху до файла, який використовується для перехресних посилань, щоб посилання не було пошкоджено, якщо файл було пересунуто або перейменовано.

• “Ми посилаємося на сторінки за ідентифікатором документа у нашій бічній панелі налаштувань, отже, зміна структури тек пізніше не призведе до небажаного розриву внутрішніх посилань.” *

---

Пошук і виявлення

** Локальний пошук проти хостованого пошуку (Algolia DocSearch) ** — Docusaurus підтримує легкий додаток локального пошуку для невеликих сайтів або хостований Algolia DocSearch для більших сайтів, які потребують швидших і більш відповідних результатів.

“Ми перейшли з локального пошуку на Algolia DocSearch, як тільки документація зросла до декількох сотень сторінок — відповідність пошуку помітно покращилася.”

---

Пояснення Docusaurus для команди документації

Situation	Phrase
Explaining docs-as-code to a new technical writer	”Every change to the docs is a pull request — the same review process engineering uses, which means changes get feedback before they go live.”
Justifying versioned docs	”Customers on the older release need to see docs that match what they actually have installed — that’s what versioning solves.”
Describing a broken link build failure	”The build isn’t broken by accident — it caught a stale internal link before it could reach production, which is exactly what it’s supposed to do.”
Discussing search choice	”Once we passed a few hundred pages, local search started returning weak results — Algolia’s hosted search noticeably improved relevance.”

Поширені помилки

• Назва ** знімок версії ** « резервна копія » — це навмисна, окремо підтримувана копія документації, пов’ язана з випуском, а не пасивний механізм резервування.
• Сказати « документація пошкоджена », коли помилка збирання є насправді ** перевіркою пошкоджених посилань **, що виконує свою роботу — відрізнити навмисну безпеку від справжньої помилки.
• Посилання на будь-який компонент React, вбудований в markdown як «просто markdown» — вміст, що використовує компоненти, є конкретно MDX, який має різні можливості і обмеження.

Практичні вправи

1. Поясніть, у двох реченнях, чому компанія може підтримувати декілька версій своєї документації одночасно.
2. Написати короткий опис PR для додавання нового попередження на основі попередження до існуючої сторінки документації.
3. Створення проекту нотатки для технічного письменника, у якій буде пояснено відмінність між « наступною » версією і поточною стабільною версією.

Зв’язані ресурси

• Англійською мовою для розробників статичного сайту Hugo
• Як писати API документацію англійською мовою

Навигація Docs Landscape — словник для Docusaurs

Погляньмо правді в очі: ефективна документація програмного забезпечення не тільки про те, що ви описуєте; це фундаментально про те, як ви передаєте цю інформацію. Як розробник Docusaurus, ви будете працювати з MDX, бічними панелями і версійною документацією — всі вони вимагають точної англійської мови, щоб забезпечити ясність і підтримку. У цьому розділі описано особливий словник, який потрібен для навігації у цьому потоці роботи і ефективної співпраці у команді з технічної документації.

Одним з найбільших викликів для носіїв мови, для яких англійська не є рідною, є перехід від буквальних перекладів до нюансів професійної англійської. Наприклад, просто сказати « ця функція * робить * щось » не так ефективно, як « ця функція * виконує * наступну операцію ». Останнє передає більш впевнене і точне розуміння. Аналогічно, такі фрази, як «це залежить від вас» можуть бути неправильно інтерпретовані; «ви відповідаєте за…» набагато ясніше і встановлює очікування. Ми також розглянемо фрази, що часто зустрічаються в оглядах коду — критичні для розвитку Docusaurus — зосереджуючись на конструктивному зворотньому зв’язку, а не на тупій критиці.

Іншою ключовою областю є термінологія, пов’язана з підходом «документи як код», який ми використовуємо з Docusaurus. Такі терміни, як «розгалуження», «запит на витягування» і «злиття» часто використовуються, і розуміння їх контексту в рамках потоку розробки програмного забезпечення є життєво важливим. Недостатньо просто знати що ці дії роблять; вам потрібно розуміти чому вони робляться — наприклад, «створення гілки дозволяє нам працювати над новими можливостями в ізоляції, не впливаючи на основну базу коду»

Нарешті, важливо освоїти словниковий запас, пов’язаний з концепціями Docusaurus, такими як компоненти MDX і бічні панелі. Знаючи різницю між « вбудованим » компонентом і « блоковим » компонентом, ви зможете ефективно структурувати вашу документацію.

Ось короткий приклад того, як це може перетворитися на повідомлення Slack:

Instead of: "This needs fixing!"
Try: "Could we explore optimizing the performance of this section? I noticed [specific observation] and suspect it's impacting page load times."

Давайте розглянемо практичний приклад, зосередившись на коментарі перегляду коду. Розробник може отримати відповідь на зразок: « Документація щодо кінцевої точки API не є зрозумілою ». Цей варіант можна було б поліпшити за допомогою таких фраз: « Мені здається, що вхідні параметри для цієї кінцевої точки дещо неоднозначні. Чи могли б ви пояснити очікувані типи даних і потенційні коди помилок?” або навіть “Було б корисно додати короткий приклад того, як викликати цю кінцеву точку.”

// Example: Docusaurus MDX component definition (simplified)
import { Docs } from "@docusaurus/core";

const MyComponent = ({ title, content }) => (
  <Docs>
    <Docs.Section title={title}>
      {content}
    </Docs.Section>
  </Docs>
);

export default MyComponent;

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