Додавання нової документації
Щоб додати нову документацію в Istio, просто дотримуйтесь наступних кроків:
- Визначте аудиторію та призначення інформації.
- Виберіть тип контенту, який ви бажаєте додати.
- Виберіть заголовок.
- Створіть свій внесок, дотримуючись наших посібників з додавання документації.
- Подайте свій внесок у наш репозиторій GitHub.
- Дотримуйтесь нашого процесу рецензування, поки ваш внесок не буде обʼєднано.
Визначення аудиторії та призначення
Найкраща документація починається з розуміння читачів, яким вона призначена, їх знань і того, що ви очікуєте від них. Інакше ви не зможете визначити відповідний обсяг і глибину інформації, ідеальну структуру або необхідну допоміжну інформацію. Ось кілька прикладів, як це працює на практиці:
Читачеві потрібно виконати певне завдання: Скажіть йому, як розпізнати, коли завдання необхідне, і надайте завдання у вигляді списку нумерованих кроків, а не просто опишіть завдання загально.
Читач має зрозуміти концепцію перед виконанням завдання: Перед завданням розкажіть про необхідну інформацію і надайте посилання на неї.
Читачу потрібно прийняти рішення: Надайте концептуальну інформацію, необхідну для розуміння, коли приймати рішення, доступні варіанти та коли вибрати один варіант замість іншого.
Читач адміністратор, але не SWE: Надайте скрипт, а не посилання на кодовий приклад в керівництві для розробників.
Читачу потрібно розширити можливості продукту: Надайте приклад розширення функції, використовуючи спрощений сценарій для ілюстрації.
Читачу потрібно зрозуміти складні взаємозвʼязки функцій: Надайте діаграму, що показує ці взаємозвʼязки, замість написання кількох сторінок контенту, який складно читати та розуміти.
Найважливіше, чого слід уникати, це поширена помилка — просто надавати читачам всю інформацію, яку ви маєте, тому що ви не впевнені в тому, яку інформацію їм потрібно.
Якщо вам потрібна допомога у визначенні аудиторії для вашого контенту, ми з радістю допоможемо і відповімо на всі ваші питання під час щодвотижневих зборів групи Docs.
Типи контенту
Коли ви зрозумієте аудиторію та призначення інформації, яку ви надаєте, ви можете вибрати тип контенту, який найкраще відповідає їх потребам. Щоб вам було легше вибрати, наведена таблиця показує підтримувані типи контенту, їхні цілі та аудиторії, для яких вони призначені:
| Тип контенту | Цілі | Аудиторії |
|---|---|---|
| Концепції | Пояснити деякий важливий аспект Istio. Наприклад, сторінка концепції описує модель конфігурації функції та пояснює її функціональність. Сторінки концепцій не містять послідовностей кроків. Натомість, надайте посилання на відповідні завдання. | Читачі, які хочуть зрозуміти, як функції працюють з базовими знаннями проекту. |
| Сторінки довідки | Надати вичерпну та детальну технічну інформацію. Звичайні приклади включають параметри API, параметри командного рядка, налаштування конфігурації та складні процедури. Контент довідки генерується з бази коду Istio і перевіряється на точність. | Читачі з глибокими технічним знанням проекту, які потребують конкретної інформації для виконання складних завдань. |
| Приклади | Описати робочий та автономний приклад, який підкреслює набір функцій, інтеграцію Istio з іншими проектами або кінцеве рішення для випадку використання. Приклади повинні використовувати існуючу установку Istio як початкову точку. Приклади повинні включати автоматизоване тестування, оскільки вони підтримуються для технічної точності. | Читачі, які хочуть швидко запустити приклад самостійно і експериментувати. Ідеально, читачі повинні мати можливість легко змінювати приклад для створення власних рішень. |
| Завдання | Показує, як досягти єдиної мети, використовуючи функції Istio. Завдання містять процедури, написані у вигляді послідовності кроків. Завдання надають мінімальне пояснення функцій, але включають посилання на концепції, які надають відповідний фон і знання. Завдання повинні включати автоматизоване тестування, оскільки вони тестуються та підтримуються для технічної точності. | Читачі, які хочуть використовувати функції Istio. |
| Сторінки налаштування | Зосереджені на кроках установки, необхідних для завершення розгортання Istio. Сторінки налаштування повинні включати автоматизовані тести, оскільки вони тестуються та підтримуються для технічної точності. | Нові та існуючі користувачі Istio, які хочуть завершити розгортання. |
| Блог-пости | Зосереджені на Istio або продуктах і технологіях, що повʼязані з ним. Блог-пости поділяються на одну з трьох категорій:
| Читачі з базовим розумінням проекту, які хочуть дізнатися про нього в звичайній, експериментальній та неформальній формі. |
| Новини | Зосереджені на своєчасній інформації про Istio та повʼязані події. Записи новин зазвичай оголошують нові релізи або майбутні події. | Читачі, які хочуть швидко дізнатися, що нового і що відбувається в спільноті Istio. |
| Записи FAQ | Надають швидкі відповіді на поширені запитання. Відповіді не вводять жодних концепцій. Натомість, вони надають практичні поради або інсайти. Відповіді повинні містити посилання на завдання, концепції або приклади в документації, щоб читачі могли дізнатися більше. | Читачі з конкретними питаннями, які шукають короткі відповіді та ресурси для подальшого вивчення. |
| Посібники з експлуатації | Зосереджені на практичних рішеннях, які вирішують конкретні проблеми, з якими стикаються під час роботи з Istio в реальних умовах. | Оператори служби мережі, які хочуть виправити проблеми або реалізувати рішення для запуску розгортань Istio. |
Вибір заголовка
Виберіть заголовок для вашої теми, який містить ключові слова, які ви хочете, щоб пошукові системи знаходили. Всі файли контенту в Istio мають імʼя index.md, але кожен файл контенту розміщується в теці, яка використовує ключові слова в заголовку теми, розділені дефісами, всі у нижньому регістрі. Тримайте імена тек якомога коротшими, щоб створення та підтримка перехресних посилань були легшими.
Подання внеску на GitHub
Якщо ви не знайомі з GitHub, перегляньте наш посібник з роботи з GitHub, щоб дізнатися, як подати зміни в документацію.
Якщо ви хочете дізнатися більше про те, як і коли публікуються ваші внески, перегляньте розділ про гілки, щоб зрозуміти, як ми використовуємо гілки та вибіркове обʼєднання для публікації нашого контенту.