Процес рецензування документації

3 хвилин(и)

Зміни до документації Istio затверджуються супроводжувачами та керівниками робочих груп Istio Docs Working Group (WG).

Рецензент документації — це довірений учасник, який затверджує контент, що відповідає критеріям прийняття, описаним у критеріях. Усі рецензії контенту дотримуються процесу, описаного в Рецензування PR контенту.

Лише супроводжувачі документації та Керівники WG можуть обʼєднувати контент в репозиторій istio.io.

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

Рецензування PR контенту

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

Учасник подає новий PR контенту в репозиторій istio.io.
Рецензент проводить огляд контенту та визначає, чи відповідає він критеріям прийняття.
Рецензент додає будь-яких технічних експертів WG, якщо учасник ще цього не зробив.
Учасник та Рецензент співпрацюють до тих пір, поки контент не відповідає всім вимогам прийняття та питання не будуть вирішені.
Якщо контент терміновий і для досягнення додаткових критеріїв прийняття потрібно значні зусилля, Рецензент подає наступне питання в репозиторій istio.io для вирішення проблем пізніше.
Учасник вирішує всі обовʼязкові та додаткові відгуки відповідно до домовленості з Рецензентом. Будь-які відгуки, зазначені в наступних питаннях, вирішуються пізніше.
Коли технічний керівник WG або супроводжувач затверджує PR контенту, Рецензент може затвердити PR.
Якщо керівник або супроводжувач Docs WG переглянув контент, він не лише затверджує, а й обʼєднує контент. В іншому випадку, супроводжувачі та керівники автоматично отримують сповіщення про затвердження Рецензента та пріоритизують затвердження та обʼєднання вже перевіреного контенту.

Наступна діаграма зображує процес:

Учасники виконують кроки в сірих формах.
Рецензенти виконують кроки в синіх формах.
Супроводжувачі документації та Керівники WG виконують кроки в зелених формах.

Наступні питання

Коли Рецензент подає наступне питання як частину процесу рецензування, GitHub issue має включати наступну інформацію:

Деталі про додаткові критерії прийняття, яким контент не відповідає.
Посилання на оригінальний PR.
Імʼя користувача технічних фахівців (Subject Matter Experts, SMEs).
Мітки для сортування питань.
Оцінка роботи: Рецензенти надають свою найкращу оцінку часу, необхідного для розвʼязання залишкових проблем разом з автором контенту.

Критерії рецензування

Наш процес рецензування дотримується нашого код поведінки завдяки прозорості наших критеріїв рецензування та їх застосуванню до всіх учасників контенту.

Критерії мають два рівні: обовʼязкові та додаткові.

Обовʼязкові критерії прийняття

Технічна точність: Щонайменше один технічний керівник WG або супрводжувач переглядає та затверджує контент.
Правильна розмітка: Усі перевірки та тести проходять.
Мова: Контент має бути чітким і зрозумілим. Щоб дізнатися більше, див. основи та загальні принципи Google developer style guide.
Посилання та навігація: Контент не має зламаних посилань, і сайт правильно будується.

Додаткові критерії прийняття

Структура контенту: Структура інформації покращує досвід читача.
Узгодженість: Контент відповідає всім рекомендаціям у посібниках по участі в Istio
Стиль: Контент відповідає Google developer style guide.
Графічні ресурси: Діаграми слідують посібнику зі створення діаграм.
Зразки коду: Контент надає відповідні, перевірені та робочі зразки коду.
Повторне використання контенту: Будь-який повторюваний контент слідує стратегії повторного використання з використанням шаблонного тексту.
Глосарій: Нові терміни додаються до глосарію з чіткими визначеннями.