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