Писання документації SDK англійською мовою

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

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

** Посібник з початку роботи ** Довідник з початкових кроків (також відомий як « швидкий початок ») — це перший розділ документації, який читає новий користувач. Його завдання полягає в тому, щоб якомога швидше перевести користувача з нуля до робочої інтеграції — зазвичай за 10 хвилин.

• Приклад: « Посібник з початкових кроків повинен призвести до роботи виклику API до кінця першої сторінки. » *

** Довідка щодо API ** Посилання на API є повним, точним описом кожного публічного класу, методу, функції і типу в SDK. Це документація, до якої користувачі повертаються неодноразово під час реалізації.

• Приклад: « Довідка API повинна містити документацію щодо кожного параметра, включаючи необов’ язкові, з їх типами і типовими значеннями. » *

** Зразок коду ** Зразок коду (або фрагмент коду) — це короткий, функціональний приклад, який демонструє, як використовувати певну функціональність. Добрі приклади коду є самодостатніми — вони повинні працювати, якщо їх скопіювати і вставити з мінімальними змінами.

• Приклад: « Кожен метод у посиланні повинен бути супроводжений прикладом коду, що показує використання в реальному світі. » *

** Журнал змін ** Журнал змін є документом, який записує всі помітні зміни між версіями SDK — нові можливості, виправлення помилок, застарілих і порушених змін. Добре підтримуваний журнал змін допомагає розробникам вирішувати, коли і чи оновлювати.

• Приклад: « Будь ласка, перевірте журнал змін перед оновленням з версії 2 до версії 3 — у модулі розпізнавання є декілька порушень ». *

** Повідомлення про знищення ** Повідомлення про застарілий код попереджає розробників про те, що можливість або метод буде вилучено у майбутній версії, надаючи їм час для переходу на рекомендовану альтернативу. Приклад: « Метод sendRequest() є застарілим. Будь ласка, використовуйте dispatch() замість цього, що забезпечує ту ж функціональність з поліпшеним обробленням помилок.”

Структура документації Good SDK

** Огляд: ** Коротке пояснення того, що робить SDK, для кого він призначений і яку проблему він вирішує. Не пиши більше трьох-чотирьох речень.

Передумов: Список того, що потрібно розробникам перед початком роботи — версія мови, дані облікового запису, команди менеджера пакунків.

** Встановлення: ** Точна команда, необхідна для встановлення SDK, для кожного з підтримуваних менеджерів пакунків.

** Початок роботи: ** Мінімальний робочий приклад, який демонструє основні варіанти використання.

** Посібники: ** Докладні навчальні матеріали, що охоплюють типові завдання. Кожен керівник повинен зосередитись на одному сценарії.

** Довідка щодо API: ** Повний, автоматично створений або написаний вручну довідник щодо всіх загальнодоступних API.

** Changelog: ** Журнал змін по версіях.

** Розв’ язання проблем: ** Розділ у стилі ЧПЗ, у якому розглянуто найпоширеніші помилки і нерозуміння.

Корисні фрази для документації SDK

• «Встановіть SDK, використовуючи свій улюблений менеджер пакунків»
• Наступний приклад демонструє, як автентифікуватися і зробити свій перший виклик API
• Всі методи асинхронні і повертають Promise
• “Параметр options не обов’язковий. Якщо не вказано, то будуть використані типові значення.”
• «Відкидає AuthenticationError, якщо надані дані невірні.»
• “Цей метод застарілий і буде вилучено у версії 4. 0. Замість цього використовуйте X»
• Див. посилання на API для повного списку доступних параметрів
• SDK сумісний з Node.js 18 і вище
• Вам буде потрібен ключ API, який ви можете отримати з панелі розробника
• Для повного робочого прикладу дивіться прикладну програму в репозиторії GitHub

Стиль написання документації SDK. Name

** Використовуйте другу особу: ** Обов’ язково звертайтеся до читача. « Ви можете налаштувати тайм- аут, передаючи об’ єкт options » є більш привабливим, ніж « тайм- аут можна налаштувати »

** Використовуйте імперативний настрій для інструкцій: ** « Додайте наступне до файла налаштувань » замість « Вам слід додати наступне. »

** Будьте чіткими щодо типів і типових значень: ** “Параметр timeout приймає число у мілісекундах. Типове значення — 5000.”

** Уникайте непотрібних кваліфікаторів: ** « Просто викликайте init() » — слово « просто » означає, що завдання є тривіальним і може розчарувати розробників, які вважають його складним.

** Покажите, а потом расскажите: ** Показуйте приклад коду, а потім пояснюйте його. Розробники спочатку шукають код.

** Пишіть для міжнародних читачів: ** Уникайте ідіом, культурних посилань і розмовних виразів. « Це шматочок торта » не означає нічого для розробника у Варшаві або Сеулі.

Поширені помилки в документації SDK

** Припустимо, що ви знаєте: ** « Налаштувати ваше середовище як зазвичай » — що таке зазвичай? Будь точніше.

** Неповний обробник помилок у прикладах: ** Показати, як обробляти помилки у прикладах коду, а не лише шлях до успіху.

Застарілі приклади: Зразки коду, що посилаються на застарілий API, підривають довіру. Налаштувати CI для перевірки збірки прикладів коду.

** Пасивне надмірне використання голосу: ** « Помилка повертається, якщо знак невірний » — хто повертає її? Напишіть: «Метод викидає InvalidTokenError, якщо термін дії токена закінчився»

Практичні рекомендації

Виберіть будь- яку бібліотеку з відкритим кодом, якою ви регулярно користуєтесь. Знайти одну з функцій або методів у документації, які, на вашу думку, є неясними або неповними. Переписати запис документації англійською мовою, використовуючи словниковий запас і принципи стилю з цієї статті. Включіть чіткий опис, документацію з параметрами, опис значення повернення і приклад коду. Порівняйте вашу версію з оригіналом і визначте, що ви поліпшили.

Національні мови: мова ненаціональних меншин

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

Одна поширена проблема виникає під час перегляду коду. Уявіть, що ви отримали такий коментар на запит на витягування: « Ця функція потребує більшої ясності. Логіка складна і важко зрозуміти. “Хоча це технічно коректно, це може бути розчаруванням для когось, чия англійська не повністю встановлена. Більш конструктивний підхід буде таким: «Чи можемо ми переглянути поток цієї функції? Додавання коментарів, що пояснюють кожен крок - особливо навколо умовного розгалуження - значно покращить читабельність і допоможе забезпечити, щоб інші розуміли заплановану поведінку. ” Ця фраза використовує м’якшу мову (“чи можемо ми переглянути”) і надає конкретні рекомендації (“додавання коментарів…”). Крім того, він зосереджується на тому, чому ясність важлива («покращити читабельність», «упевнитися, що інші розуміють»), а не просто зазначає проблему. Також корисно проактивно запитувати, якщо їм потрібні пояснення — «Чи є у вас якісь питання щодо цього розділу? Чи хотіли б ви, щоб я розглянув обґрунтування за вибором дизайну?» — демонструючи підтримку і готовність пояснити речі різними способами.

Інший сценарій включає в себе створення описів PR. Замість того, щоб сказати, « Реалізована нова функція X », більш детальний опис буде таким: « Цей запит на збирання реалізує функцію X, яка дозволяє користувачам [ясно вказати функціональність]. Реалізація використовує [короткий опис ключових технічних компонентів] і розв’ язує [згадайте будь- які пов’ язані проблеми або залежності]. Дизайн дотримується найкращих практик модульності і підтримки. ” Зауважте включення активного голосу (« дозволяє користувачам »), конкретні подробиці про * що * і * чому *, а також посилання на встановлені принципи. Використання фраз на кшталт «дотримується найкращих практик» демонструє професіоналізм і заохочує фокусування на довгостроковій підтримці, що часто цінується в глобальних командах розробників. Заохочення розробників використовувати точки з кулями при описі складних змін також може бути неймовірно корисним - розбиття інформації на перетравлювані шматки значно зменшує когнітивне навантаження.

І, нарешті, не недооцінюйте цінність надання ресурсів. Невеликий словник часто використовуваних технічних термінів, підібраний відповідно до специфічного словника вашого SDK, може виявитися безцінним. Розгляньте можливість створення спільного каналу Slack, присвяченого запитанням і отриманню підтримки, сприяючи створенню співробітницького середовища, де розробники відчуватимуть себе комфортно, шукаючи допомоги без страху судження. Пам’ятайте, що терпіння і емпатія є ключовими - розуміння проблем, з якими стикаються носії англійської мови, які не є рідними для них, в кінцевому підсумку призведе до більш ефективного спілкування і плавнішого процесу розвитку для всіх зацікавлених.