Отже, питання ось у чому: Що розробляють софтверні компанії? Програмне забезпечення, так! Але, на жаль чи на щастя, це не єдине, про що мають турбуватися такі компанії. Програмне забезпечення - це чудово, але воно марне, якщо ніхто не знає, як ним користуватися. Отже, що ще розробляють софтверні компанії? Документацію до програмного забезпечення.

Хто створює програмну документацію і хто повинен це робити

Робочі процеси створення документації відрізняються в різних компаніях. Це завдання можуть виконувати різні відділи: Розробники, QA-інженери, технічні письменники тощо. З різних причин деякі компанії просто не мають у своєму штаті команди технічної документації. У такому випадку у компанії-розробника програмного забезпечення є кілька варіантів: шукати автора серед аутсорсингових компаній або виділити частину поточних ресурсів на цю задачу. Досить часто ми бачимо компанії, де написанням технічної документації займаються Dev & QA. Нащадками Шекспіра цих людей точно не назвеш, це здебільшого технічні фахівці, а не поети (за рідкісним винятком, я впевнений 🙂 ), тому ні розробники, ні тестувальники не в захваті від цієї додаткової роботи. І це цілком зрозуміло - у них, безумовно, є більш пріоритетні завдання. У таких ситуаціях якість посібника користувача може постраждати. Саме тому багато компаній вважають за краще мати в штаті технічних письменників. Але, по правді кажучи, не всі розуміють, що таке “технічний письменник”. Щоб прояснити це раз і назавжди - технічні письменники - це люди, які створюють всі види технічної документації (посібники користувача, інструкції, бази знань, контекстну допомогу і т.д.). Вони дізнаються про кожну нову функцію або зміну до того, як відбудеться реліз, оскільки їм потрібно описати кожну деталь для кінцевих користувачів. Якщо якась функція або вузьке місце не задокументовані, швидше за все, армія розлючених користувачів нагострить вила, запалить факели і піде на дружню бесіду з… службою технічної підтримки. Отже, техрайтери з’явилися на світ не лише для того, щоб покращити користувацький досвід за допомогою написання довідкових статей, але й для того, щоб зменшити навантаження на службу підтримки.

А як щодо контролю якості?

З цим розібравшись, давайте ближче познайомимося з самою документацією. Слово, яке я б підібрав, щоб описати її для софтверної компанії - неминуча. Не має значення, чи ви використовуєте гнучку розробку програмного забезпечення, чи модель водоспаду - ви не можете уникнути написання інструкцій користувача під час кожного спринту (злий сміх.mp3). Важко відокремити програмну документацію від R&D. Та це й не потрібно - документація так само важлива для програмного продукту, як і його код. Здається, ми не можемо уникнути наступного висновку: з технічною документацією слід поводитися правильно. Наприклад, посібники користувача повинні бути протестовані. І команда QA є найкращим вибором для тестування посібників користувача. Тому що, по суті, техрайтери і тестувальники є першими реальними користувачами нових функцій. Отже, вони першими дізнаються, коли щось незручно, незрозуміло, занадто складно і т.д.

Коли технічні автори документують функцію або екран програми, їм може здатися, що це нормально в контексті призначення функції. У той час як команда QA подивиться на те ж саме під іншим кутом. Якщо ви дасте цю функцію на перевірку тестувальникам, вони можуть отримати своєрідний зворотній зв’язок - QA подивиться на це з практичної сторони, вони зосереджені на реальному користувацькому досвіді роботи з функціоналом продукту. Отже, тестувальники можуть звернутися до команди документації і попросити їх переписати статтю або доопрацювати опис. Іноді буває навпаки - команда QA читає документацію, в якій описано, як має працювати певна функція, і розуміє, що це працює не так, як очікувалося, і це баг, про який вони нічого не знали. Як бачите, така командна співпраця може бути дуже продуктивною і корисною для покращення як документації, так і якості програмного забезпечення.

Співпраця QA та технічних авторів: Як це зробити

Як має бути організована ця командна співпраця? Який робочий процес буде достатнім? Найпростіший спосіб - це електронна пошта. Створюється документ, він надсилається електронною поштою. Пізніше ви отримуєте зворотній зв’язок і вносите необхідні зміни в початковий документ. Таку схему використовують багато компаній. Те, що вона популярна, не означає, що вона хороша. Просто зупиніться на секунду і подумайте про всі недоліки такого підходу: листи потрапляють до папок зі спамом, не доставляються взагалі, губляться серед сотень інших повідомлень. Цей процес довгий і болісний. Давайте пошукаємо більш формалізований підхід до розгляду документів, який не має цих проблем.

Зрозуміло, що рішення залежить від інструменту, яким користуються технічні письменники для створення документації. Наприклад, MS Word - поганий вибір програмного забезпечення для створення програмної документації. Існує широкий спектр спеціалізованих інструментів для створення програмної документації, призначених для полегшення співпраці та перегляду документації. Як правило, такі інструменти мають спеціальний робочий процес для документів - правонаступник, статус тощо. Це дуже корисно з точки зору розуміння того, хто працює над документом в даний момент і на якому етапі він знаходиться (чернетка, на розгляді, готовий). Крім того, подібні системи часто дозволяють додавати коментарі, тож рецензент може залишити свої зауваження до змісту, щоб автор міг врахувати їх пізніше. Веб-інструменти для документування (наприклад, ClickHelp) є найкращим вибором для цього завдання, оскільки вони не вимагають встановлення клієнтської програми для співпраці з командою документування. Єдине, що вам потрібно - це браузер. Це спрощує створення правильної та ефективної схеми перегляду документації між технічними письменниками та тестувальниками.

Висновок

Співпраця дуже часто є ключем до успіху. Спробуйте застосувати підхід, описаний у цій статті - залучіть вашу команду контролю якості до роботи над документацією і переконайтеся, що ваші технічні
автори використовують хороший інструмент для роботи з документацією. Це підвищить якість посібника користувача, збільшить задоволеність користувачів вашим програмним забезпеченням і навіть може збільшити кількість успішних пробних користувачів, які перетворюються на клієнтів. *Про автора - команду ClickHelp* Цей гостьовий блог був написаний розробником інструменту онлайн-документації ClickHelp. ClickHelp - це сучасний хмарний інструмент на основі браузера. Він може створювати онлайн і друковану документацію, бази знань, PDF-документи, контекстну допомогу, політики і процедури. ClickHelp поєднує в собі середовище створення документації для команд і портал документації для кінцевих користувачів. Щоб дізнатися більше про інструмент документації ClickHelp, відвідайте цей веб-сайт: https://clickhelp.co