На майбутній конференції APIStrat у Портленді Тейлор Барнетт вивчить різні принципи проектування документації та обговорить найкращі практики.
Тейлор Барнетт, інженер спільноти в Keen IO, каже, що практика та постійні ітерації є ключовими речами для написання гарної документації. На майбутній конференції зі стратегії та практики API 2017, яка проходитиме з 31 жовтня по 2 листопада в Портленді, Барнетт пояснить різні типи документацій та опише деякі найкращі практики.
У своїй бесіді - "Речі, про які я хочу, щоб люди говорили мені при написанні документацій" - Барнетт розгляне, як люди використовують документацію та обговорюють інструменти та тактики включення інших членів команди до написання документації. Барнетт пояснює глибше у цьому відредагованому інтерв'ю.
Linux Foundation: Що привело вас до цієї розмови? Чи зустрічалися вам проекти з поганою документацією?
Тейлор Барнетт: Торік мій товариш по команді, Меггі Ян, і я очолювали роботу над покращенням контенту та документації для розробників у Keen IO. Не секрет, що розробники люблять чудову документацію, але багато компаній, які розробляють API, не завжди оснащені ресурсами, щоб мати таку. В результаті всі ми стикаємося з великою кількістю поганої документації, коли намагаємось використовувати інструменти розробника та API.
Linux Foundation: Часто існує команда розробників документації, і є розробники, які написали частину програмного забезпечення; і ті й ті є експертами у своїх сферах, але їм потрібно добре вміти співпрацювати для створення придатних для використання документацій. Як можна досягти такого рівня співробітництва?
Барнетт: У великих компаніях це безперечно може бути правдою, хоча в багатьох компаніях документація, як і раніше, належить різним командам. Тим не менш, потреба в поліпшенні взаємодії, як і раніше, є. Один із способів покращити співпрацю – писати документацію в процесі розробки продукту на ранньому етапі. Якщо ви зачекаєте, доки все буде зроблено і продукт буде готовий до випуску, люди, які пишуть документацію, будуть почуватися відірваними від процесу і вважати себе другорядними. Якщо люди, які працюють над розробкою продукту, співпрацюють на ранньому етапі, покращується не лише продукт, а й документація. Люди, які пишуть документацію зазвичай проводять деякий час, щоб зрозуміти API або інструмент, про який вони пишуть, тому вони стають тільки краще, коли можуть працювати з людьми, які цей продукт розробляють. Крім того, вони можуть дати більший зворотний зв'язок з точки зору користувача набагато раніше.
Ще один спосіб покращити співпрацю – залучити більше людей до процесу огляду документації. Ми проводимо більшу частину наших оглядів документації у GitHub. Це чудово тим, що код оглядають не лише хтось у ролі редактора, а й люди з команди інженерів та команди продакшена. Це збільшує кількість різнобічних поглядів на документацію та допомагає зробити її кращою.
Linux Foundation: Як слід розробникам підходити до документації?
Барнетт: Більшість розробників добре знайомі з ідеєю Test Driven Development (TDD), але наскільки знайомі вони з розробкою Documentation Driven Development (DDD)? Кроки DDD:
- Напишіть або оновіть документацію,
- Отримайте відгуки про цю документацію,
- Напишіть тест на відмову відповідно до цієї документації (TDD),
- Напишіть код для проходження тесту на відмову,
- Повторіть.
Це може бути чудовим способом для розробників заощадити велику кількість часу і не витрачати його надто багато на погано розроблені функції. Як говорить Ісаак Шлютер, співзасновник npm, про розробку документації – «Це ефективний спосіб підвищити продуктивність за рахунок скорочення як частоти, так і вартості помилок». Наш мозок може зберігати обмежену кількість інформації одночасно. У комп'ютерних термінах розмір нашої робочої пам'яті досить малий. Записування інформації, про яку ми думаємо, це спосіб «вивантажити значний шмат думок без втрат даних», дозволяючи нам думати повільніше і обережніше.
Наприклад: У Keen IO ми нещодавно розділили нашу бібліотеку JavaScript на три різні модулі. Це рішення було надихнуте документацією, яку ми підтримували. Ми спробували впорядкувати документацію, але її було надто багато, щоб охопити всю з обмеженою увагою. У шумі було приховано багато важливих деталей і функцій. Наприклад, якби вся документація була написана раніше, можливо, ми ухвалили це рішення раніше.
Крім того, розробнику, який сам пише документацію, важливе постійне повторення та практика. Ваша перша версія документації не буде відмінною, але, зосередившись на спробі написати зрозумілий текст, згодом вона стане кращою. Крім того, важлива наявність іншої людини, не знайомої з продуктом, яка може зробити огляд вашої документації.
Linux Foundation: якщо розробники пишуть документацію для інших розробників, як вони можуть думати як користувачі?
Барнетт:
Раніше я думав, що розробники – це найкращі люди для того, щоб писати документацію для інших розробників, бо вони самі ними є. Я, як і раніше, вважаю, що це частково вірно, т.к. деякі розробники мають велику кількість знань. Якщо минуло якийсь час, після того, як розробник щось вивчив, може існувати так зване «прокляття знання». Чим більше ви знаєте, тим більше ви забуваєте, як це було раніше. Ось чому я люблю говорити про емпатичну документацію.
Вам потрібно співпереживати користувачеві на іншому кінці. Не думайте, що він знає, як щось зробити, дайте користувачеві ресурси, щоб заповнити кроки, які можуть здатися вам «легкими». Крім того, думка, що щось «легко» чи «просто», коли це не працює у користувача, – це найстрашніше почуття для нього. Це змушує ваших користувачів сумніватися у собі, відчувати розчарування та купу інших негативних емоцій. Завжди намагайтеся пам'ятати, що вам потрібно бути чуйним!
Linux Foundation : Наскільки важливими є інструменти для створення документації?
Барнетт: Дуже важливі! Раніше я згадував використання GitHub для оглядів. Я також рекомендував би провести постійне інтеграційне тестування на вашому сайті документації, якщо ви не використовуєте таку послугу як ReadMe або Apiary, щоб переконатися, що ви її не зламаєте. Пов'язана з цим тема: ви створюєте свій власний продукт або використовуєте сервіс? Інструменти можуть бути корисними, але вони можуть бути не завжди оптимальними. Ви повинні знайти баланс на основі поточних ресурсів. Нарешті, я рекомендував би спробувати книгу Енн Джентль, "Docs Like Code". Вона багато разів порушує тему інструментів у книзі.
Linux Foundation: Кому слід бути присутнім на вашій сесії?
Барнетт: Всім! Просто жартую. Якщо ви є кимось у ролі розробника, таким як розробники взаємин, євангелісти, адвокати, маркетологи і т. д., якщо ви знаходитесь в команді продакшена розробником продукту або платформи, або якщо ви розробник або інженер, який хоче писати відмінні документації.
Linux Foundation: Який основний посил вашої розмови?
Барнетт: Будь-хто може писати документації, але з деякою практикою, ітерацією та роботою над різними навичками написання документації кожен зможе писати відмінну документацію.
Дізнайтесь більше в розмові Тейлор Барнетт на конференції APIStrat, яка відбудеться з 31 жовтня - 2 листопада в Портленді, штат Орегон.
