Гарна документація цінується, вона допомагає: прискорює розробку та пояснює неоднозначні моменти. Погана – заплутує та відбиває бажання працювати з продуктом.
Зі стрімкими циклами випуску продуктів та розвитком команд розробників, забезпечити актуальну та доступну документацію складно.
Разом з Quality Assurance Group склали список з 7 кроків, дотримання яких допоможе створити точний та цікавий технічний опис.
Уніфікуйте
Поширена проблема – різні розділи документації написані по-різному. Кожен автор використовує власний стиль написання. Як вирішити проблему? Сформуйте редакційну політику – набір правил для оформлення. Вимагайте від нових авторів дотримуватися цих правил.
Знайте свого читача
Іноді документація занадто складна для розуміння, а іноді навпаки – настільки деталізована, що читачу потрібно вишукувати в тексті необхідні частини опису.
Потрібно розуміти хто читатиме ваші інструкції та писати їх мовою, зрозумілою для цього читача. Якщо це досвідчені розробники – не пояснюйте базові концепції. Якщо новачки – деталізуйте опис. Поняття і слова, які ви розумієте, можуть бути повністю незнайомі читачеві. Одне слово без пояснень, може підштовхнути читача припинити ознайомлення.
Усувайте будь-які неточності
Базове правило, якого часто не дотримуються. Точний документ не містить спотворень та неоднозначних виразів. Якщо читач при ознайомленні з вашою документацією змушений витрачати час на з'ясування, що ж ви намагаєтеся йому повідомити, – ви його заплутали. Як тільки це відбулось, вважайте, ви втратили потенційного клієнта для продукту, який описує ваша документація.
Не пропускайте кроки
Повний документ не упускає нічого важливого для читача. Якщо ви пишете довідковий посібник, переконайтеся, що він містить усі команди. Якщо ви пишете процедуру, переконайтеся, що нема відсутніх кроків. Якщо ви описуєте помилки, які користувач може побачити в системі, переконайтеся, що в ньому містяться усі повідомлення про помилки. Якщо ви пропустите хоча б одне, і користувач побачить його в системі, впевненість у повноті й точності вашої документації буде порушена.
Дотримуйтесь послідовності
Під час написання інструкцій для серії операцій переконайтеся, що ви виконуєте операції в правильному порядку. Чіткий порядок дій допоможе користувачам не заплутатись.
Поганий приклад. Ці інструкції є зворотними та потребують обробки користувачем:
- Виберіть «Параметри» в меню «Інструменти».
Хороший приклад. Ці вказівки є правильними та не вимагають жодних зусиль від користувача:
- Виберіть «Інструменти» – «Параметри»
Корисний документ – це той, який читач може легко використовувати. Не надто громіздкий і не створений таким чином, що потрібно докласти зусиль, щоб знайти необхідну інформацію. Правильно сформована структура є тим кістяком, навколо якого формується ваш документ.
Ілюструйте
Око приваблюють зображення. Коли людина читає посібник, її око спочатку переходить до зображень, а лише потім читач дивиться на текст навколо цього зображення. При звернені до ілюстрацій читачам потрібен контекст, щоб внести ясність. Використовуйте підписи, щоб усунути неясність з ілюстраціями.
Додаючи ілюстрацію в опис, стежте за тим, щоб посилатися на неї в тексті зазначенням її номера і таких слів як «вище», «вгорі», «нижче», «внизу». Неприпустимо змушувати читача під час читання вашої роботи витрачати час на прив'язку ілюстрації до тексту або на її пошук в описі. Якщо ви додаєте в текст, скажімо, «Рис. 1 », то переконаєтеся, що десь в тексті сказано щось на кшталт «див. Рис. 1 внизу».
Не розраховуйте створити ідеальну документацію з першої спроби
Написати хороші інструкції з першої спроби складно. Треба досконало дослідити продукт, визначити місця, які потребують особливої уваги. Нехай перша версія буде своєрідним кістяком, який допоможе зрозуміти вам куди рухатись далі. У наступній версії додайте ясність і точність: перевірте факти, додайте ілюстрації, перегляньте структуру. Кожна ітерація буде прибирати з вашого документу слабкі місця та привносити в документацію щось нове.
18 вересня розпочнеться осінній курс тестування програмного забезпечення від Quality Assurance Group. 162 навчальні години та працевлаштування.
Коментарі (1)