Англійська мова для Backstage Developer Portal

Засновники обговорення обертаються навколо певного набору іменників для організації інженерних знань - каталог, суб’єкт, шаблон - і команди, які нові для платформи, часто досягають нечітких слів, таких як “сторінка” або “список послуг”, які не відповідають тому, як Backstage насправді моделює програмне забезпечення.

Ключовий словник

** Каталог програмного забезпечення ** — центральний, підданий запиту перелік всіх компонентів, API і ресурсів, що належать організації, заповнений з файлів метаданих YAML, які було перевірено у кожному сховищі. “Перед тим, як ми зможемо створити звіти про власників, кожна служба повинна мати запис у каталогу програмного забезпечення — зараз половини з них не вистачає.”

** Сутність ** — один елемент, зареєстрований у каталогу, наприклад, компонент, API, система або користувач, кожен з яких описано файлом catalog-info.yaml з визначеним типом і метаданими. “Ця мікросервіс не з’ являється, тому що в її файлі сутності відсутнє поле spec.owner — каталог не може зареєструвати її без нього.”

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

• “Перенесіть цей підручник до TechDocs замість сторінки вікі — він буде поруч з кодом і буде автоматично відновлюватися при кожному об’ єднанні.” *

** Шаблон теки скелі ** — проект, який можна використовувати повторно, який створює нове сховище зі стандартною структурою, налаштуваннями CI і реєстрацією каталогу, коли розробник створює нову службу.

• “Використовувати шаблон scafffolder для нових служб замість копіювання старого сховища — типово він правильно підключить запис каталогу і конвеєр.” *

** Власник ** — поле метаданих об’ єкта, яке визначає, яка команда відповідає за компонент, використовується для керування маршрутизацією за викликом, фільтрування каталогу і відповідальності у перегляді подій. “Каталог показує, що цей API не має чіткого власника — це перша річ, яку потрібно виправити, перш ніж ми зможемо навіть пошукати правильну команду.”

Звичайні фрази

• Чи дійсно ця служба зареєстрована в каталозі, чи ми просто припускаємо, що вона існує?»
• Чи має ця сутність власний набір, або це все ще вказує на команду-замінник?»
• Чи повинна ця документація жити в TechDocs, чи вона належить десь іншому повністю?»
• Чи є шаблон для такого типу послуги, або ми починаємо з нуля?»
• Що говорить каталог про те, що залежить від цього API, перш ніж ми його використовуємо?»

Приклади висловлювань

Пояснення поліпшення під час запуску:

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

Обговорення інциденту, що стосується ретро-визначення: “Ескаляцію було відкладено, оскільки в каталозі для цієї служби все ще вказано неправильну команду як власника — ми перевіряємо поля власника в каталозі цього тижня.”

Опис перенесення документації: “Ми перенесли runbooks розгортання в TechDocs, щоб вони були версовані з кодом і переглянуті в тих же запитах на витягування, замість того, щоб зникати з синхронізації в окремій вікі.”

Професійні поради

• Використовуйте ** entity ** замість « service », коли обговорюєте каталог абстрактно — об’ єкт може бути компонентом, API, системою або ресурсом, а слово choice сигналізує, який тип ви маєте на увазі.
• Вимагати точних метаданих власності у дискусіях щодо вступу — застарілі поля власності є поширеною причиною повільної реакції на інциденти.
• Рекомендуємо TechDocs за назвою, а не за загальною «документацією», коли пропонуєте, де має знаходитися вміст — це сигналізує про конкретне, версійне, кодово- сусіднє рішення, а не просто ще одну сторінку вікі.
• Посилайтеся на шаблон scaffolder, коли обговорюєте створення нової служби — це конкретний важіль для забезпечення стандартів, більш дієвий, ніж сказати «ми повинні мати конвенції»

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

1. Поясніть, що таке каталог програмного забезпечення і яку проблему він вирішує.
2. Описати різницю між типом сутності і її полем власника.
3. Напишіть речення, у якому поясните, чому TechDocs, що мешкає поряд з кодом, має перевагу перед окремою вікі.

Переклади: «Переклад з німецької мови»

Краса Backstage – і його основна цінність – полягає не тільки в його технічних особливостях (вражаючих лесах, детальній технічній документації), але також в тому, наскільки ефективно він комунікує. Для людей, для яких англійська не є рідною мовою, особливо для тих, хто не знає професійної термінології розробки програмного забезпечення, буквальний переклад «технічної документації» або «порталу розробників» може бути неймовірно заплутаним і, чесно кажучи, безглуздою. Це набагато ефективніше, щоб вивчити конкретні фрази, використовувані в контексті Backstage - термінологія, яка визначає його функцію і значення. Це не про ідеальну граматику; це про прийняття мови процвітаючої екосистеми, де точне спілкування є найважливішим для співпраці, ефективного розвитку і чіткого власника. Задумайтесь, як ви поясните складну систему комусь, хто не розмовляє вашою рідною мовою — ви не просто викидали б жаргон!

Одна з найпоширеніших областей плутанини виникає з концепції «власності» в Backstage. Це не просто призначення відповідальності; це встановлення чіткого ланцюга відповідальності за конкретні технічні документи, шаблони скелетних файлів і навіть цілих об’єктів в рамках каталогу. Фрази на кшталт «власність суб’єкта» навмисно вибираються для передачі цієї зосередженої відповідальності. Аналогічно, розуміння різниці між «шаблоном леса» і «TechDoc» є ключовим - вони представляють різні етапи в життєвому циклі документації. Використання цих точних термінів уникає неоднозначності і дозволяє розробникам швидко зрозуміти, що саме слід робити. Не бійтеся запитати про пояснення, якщо ви зустрінете незнайому мову; швидке запитання може запобігти значним непорозумінням. Ціль - не вільне спілкування, а ефективне спілкування в цьому конкретному технічному середовищі.

Крім того, навіть здавалося б прості фрази, такі як «рефактор» або «upstream» мають певні конотації в спільнотах відкритого коду і розробки програмного забезпечення. Хоча їх буквальні значення можуть бути зрозумілими, вони часто використовуються з певною частотою і очікуванням - наприклад, в розмовах Slack щодо перегляду коду. Виявлення цих тонких нюансів є ключем до ефективної участі. Задумайтеся про те, як ви пояснили б * чому * щось потребує переробки або * куди * зміни слід відправити. Ці дрібні деталі значно сприяють ясному спілкуванню і спільному вирішенню проблем.

# Example: Using `backstage` CLI to list entities with a specific tag
backstage entity list --tag "payments" --format json

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