Документація до софту – це просто набір статей. Але навіть вони можуть вивести із себе. Спочатку довго шукаєш потрібну інструкцію. Потім розумієшся на малозрозумілому тексті. Робиш, як написано, а проблема не вирішується. Шукаєш іншу статтю, нервуєшся… За годину плюєш на все і йдеш. Так працює погана документація. Що робить її такою і як це виправити — читайте під катом.
У нашій старій документації було багато недоліків. Вже майже рік ми переробляємо її, щоб описаний вище сценарій не стосувався наших клієнтів. Подивіться, и .
Проблема 1. Незрозумілі, погано написані статті
Якщо в документації неможливо розібратися, який у ній сенс? Але ніхто не пише незрозумілі статті спеціально. Вони виходять, коли автор не думає про аудиторію та мету, ллє воду і не перевіряє текст на помилки.
- Аудиторія. Перед написанням статті слід подумати про рівень підготовки читача. Логічно, що в статті для новачка не варто пропускати базові кроки і залишати технічні терміни без розшифровки, а в статті з рідкісної фічі, потрібної лише профі, розжовувати значення слова PHP.
- Мета. Ще одна річ, про яку краще подумати наперед. Автор повинен поставити чітку мету, визначити корисну дію статті, вирішити, що зробить читач після її прочитання. Якщо цього зробити, вийде опис заради опису.
- Вода та помилки. Багато зайвої інформації та канцеляризмів, помилки та друкарські помилки заважають сприйняттю. Навіть якщо читач не грамар-наці, недбалість у тексті може його відштовхнути.
Врахуйте поради вище, і статті стануть зрозумілішими — гарантовано. Щоб зробити ще краще, візьміть на озброєння наші .
Проблема 2. Статті не відповідають на всі питання
Погано, коли документація не встигає за розробкою, не відповідає реальним питанням, помилки в ній не виправляються роками. Це проблеми не так автора, як організації процесів усередині компанії.
Документація не встигає за розробкою
Фіча вже в релізі, маркетинг планує її висвітлювати, і тут виявляється, що нової статті чи перекладу досі немає в документації. Нам через це доводилося навіть відкладати реліз. Можна скільки завгодно просити всіх вчасно передавати завдання технічним письменникам, але це не спрацює. Якщо процес не автоматизувати, ситуація повторюватиметься.
Ми внесли зміни до YouTrack. Завдання на написання статті про нову фічу падає технічному письменнику в той самий момент, коли можливість починають тестувати. Тоді ж про неї дізнається маркетинг, щоб підготуватись до просування. Повідомлення надходять ще й у корпоративний месенджер Mattermost, тому пропустити новини від розробників просто неможливо.
Документація не відображає запитів користувачів
Ми звикли працювати так: фіча вийшла, ми про неї розповіли. Описали, як увімкнути, вимкнути, зробити тонкі налаштування. Але що, якщо клієнт застосовує наше програмне забезпечення так, як ми не припускали? Чи у нього виникають помилки, про які ми не подумали?
Щоб документація була максимально повною, радимо проаналізувати звернення на підтримку, запитання на тематичних форумах, запити у пошукових системах. Найпопулярніші топіки передати технічним письменникам, щоб вони доповнили існуючі статті або написали нові.
Документація не вдосконалюється
Складно зробити одразу ідеально, помилки все одно будуть. Можна сподіватися на зворотний зв'язок від клієнтів, але навряд чи вони будуть повідомляти про кожну друкарську помилку, неточність, незрозумілу або незнайдену статтю. Окрім клієнтів, документацію читають співробітники, а отже, бачать ті самі помилки. Це можна використати! Треба тільки створити умови, в яких легко повідомити проблему.
У нас є група на внутрішньому порталі, де співробітники залишають зауваження, пропозиції та ідеї щодо документації. Підтримці потрібна стаття, а її немає? Тестувальник помітив неточність? Партнер поскаржився менеджерам із розвитку на помилки? Все в цю групу! Технічні письменники щось виправляють одразу, щось переносять у YouTrack, щось беруть на подумати. Щоб тема не затихла, час від часу ми нагадуємо про існування групи та важливість зворотного зв'язку.
Проблема 3. Потрібну статтю доводиться довго шукати
Стаття, яку не можна знайти, нічим не краща за статтю, якої немає. Девізом хорошої документації має бути фраза "Легко шукати, легко знайти". Як цього досягти?
Упорядкувати структуру та визначити принцип вибору тем. Структура має бути максимально прозорою, щоб читач не замислювався: «А де можна знайти цю статтю?». Якщо узагальнити, то є два підходи: від інтерфейсу та від завдань.
- Від інтерфейсу. Зміст дублює розділи панелі. Так було в старій документації ISPsystem.
- Від завдань. Назви статей та розділів відображають завдання користувачів; у заголовках майже завжди є дієслова та відповіді на питання «як зробити». Нині ми переходимо до такого формату.
Який би підхід ви не обрали, переконайтеся, що тема відповідає запитам користувачів та освітлена так, щоб користувач точно вирішив своє питання.
Налагодити централізований пошук. В ідеальному світі пошук повинен працювати, навіть коли опечатаєшся чи помилишся з мовою. Наш пошук у Confluence поки цим порадувати не може. Якщо у вас багато продуктів, а загальна документація, адаптуйте пошук під сторінку, на якій знаходиться користувач. У нашому випадку пошук на головній працює по всіх продуктах, а якщо ви вже знаходитесь у конкретному розділі, то лише за статтями у ньому.
Додати зміст та «хлібні крихти». Добре, коли на кожній сторінці є меню та хлібні крихти - шлях користувача до поточної сторінки з можливістю повернутися на будь-який рівень. У старій документації ISPsystem треба було вийти зі статті, щоб потрапити до змісту. Було незручно, тож у новій ми це поправили.
Розставити посилання у продукті. Якщо люди раз у раз приходять на підтримку з тим самим питанням, розумно додати підказку з його рішенням в інтерфейс. Якщо у вас є дані або розуміння, коли користувач стикається з проблемою, ви також можете повідомити його розсилкою. І турботу виявите, і навантаження з підтримки знімете.
Праворуч у спливаючому вікні посилання на статтю про налаштування DNSSEC у розділі керування доменами ISPmanager
Налаштувати перехресні посилання усередині документації. Статті, які пов'язані між собою, мають бути «залінковані». Якщо статті є послідовністю, обов'язково додайте в кінці кожного тексту стрілки вперед і назад.
Швидше за все, людина спочатку піде шукати відповідь на своє запитання не до вас, а до пошукової системи. Прикро, якщо посилань на документацію там не буде з технічних причин. Тож подбайте про пошукову оптимізацію.
Проблема 4. Застаріла верстка заважає сприйняттю
Окрім поганих текстів документацію може зіпсувати дизайн. Люди звикли читати добре згорблені матеріали. Блоги, соцмережі, медіа - весь контент подається не просто красивим, а й зручним для читання, приємним для ока. Тому легко можна зрозуміти біль людини, яка бачить текст як на скріншоті нижче.
У цій статті скріншотів та виділень так багато, що вони не допомагають, а лише заважають сприйняттю (картинка клікабельна)
Не варто робити з документації лонгрід із купою ефектів, але базові правила врахувати потрібно.
Верстка. Визначте ширину основного тексту, шрифт, розмір, заголовки та відступи. Залучіть дизайнера, а щоб приймати роботу чи впоратися самостійно, прочитайте книгу Артема Горбунова «Друкарня і верстка». У ній представлений лише один із поглядів на верстку, але його цілком достатньо.
виділення. Визначте, що вимагає акцентів у тексті. Зазвичай це шлях в інтерфейсі, кнопки, вставки коду, файли конфігурації, блоки «Зверніть увагу». Вкажіть, якими будуть виділення цих елементів і зафіксуйте в регламенті. Майте на увазі, що чим менше виділень, тим краще. Коли їх багато, текст «шумить». Шум створюють навіть лапки, якщо використовуються дуже часто.
Скріншоти. Договоріться з командою, у яких випадках потрібні скріншоти. Ілюструвати кожен крок точно немає потреби. Велика кількість скріншотів, у т.ч. окремих кнопочок, заважають сприйняттю, псують верстку. Визначте розмір, а також формат виділень та підписів на скріншотах, зафіксуйте у регламенті. Пам'ятайте, що ілюстрації завжди повинні відповідати написаному та бути актуальними. Знову ж таки, якщо продукт регулярно оновлюється, встежити за кожним буде складно.
Довжина тексту. Уникайте надто довгих статей. Дробите їх на частини, а якщо неможливо, додавайте на початок статті зміст з якорними посиланнями. Простий спосіб зробити статтю візуально коротшим - приховати технічні деталі, потрібні вузькому колу читачів, під спойлером.
формати. Поєднуйте у статтях кілька форматів: текст, відео та зображення. Це покращить сприйняття.
Не намагайтеся прикрити проблеми гарною версткою. Чесно, ми самі сподівалися, що обгортка врятує застарілу документацію — не вийшло. У текстах було стільки візуального шуму та зайвих подробиць, що регламент та нове оформлення були безсилі.
Багато з описаного вище визначатиметься майданчиком, який ви використовуєте для документації. У нас, наприклад, це Confluence. З ним теж довелося повозитися. Якщо цікаво, прочитайте розповідь нашого веб-девелопера: .
З чого почати покращення і як вижити
Якщо ваша документація така ж неосяжна, як у ISPsystem, і ви не знаєте, за що хапатися, почніть із найсерйозніших проблем. Клієнти не розуміють доку — займіться покращенням текстів, зробіть регламенти, навчіть письменників. Документація неактуальна - візьміть за внутрішні процеси. Почніть із найпопулярніших статей про найбільш затребувані продукти: запитайте підтримку, подивіться аналітику сайту та запити у пошукових системах.
Скажімо одразу — легко не буде. І швидко теж навряд чи вийде. Хіба що ви тільки починаєте і одразу робите правильно. Одне знаємо точно – згодом стане краще. Але процес ніколи не закінчиться :-).
Джерело: habr.com