10 вредных советов для документации
Наша команда много лет занимается разработкой программы для создания пользовательской документации. За это время мы столкнулись с бесчисленным множеством руководств, анализировали и проверяли документацию наших клиентов, создавали свою собственную документацию, добавляли новые фичи, например, шаблоны.
В общем, наш путь был долог и интересен, но он еще далеко не закончился. Сегодня хочу поделиться с вами опытом технического писателя и в немного (или много) сатирической форме предостеречь от классических, но очень серьезных ошибок при написании и публикации пользовательской документации, с которыми часто сталкивались в руководствах наших клиентов.
Если вы все-таки решились прочитать сие творение, то сразу скажем, лучший способ заставить пользователей ненавидеть вас и вашу документацию — не написать её. Правильно, зачем она нужна, ведь мы живем в 21-м веке, интерфейс у нас интуитивно понятен, каждый разберется какие кнопки за что отвечают, как успешно выполнять задачи и решать нетиповые проблемы, да?
(Автор пытается намекнуть, что пользовательская документация, даже в наше время все еще востребована, каким бы понятным и простым не был пользовательский интерфейс. Пользователи бывают разные и программы чаще всего бывают сложные. Конечно, вам, как разработчикам, кажется, что все просто. Это не так)
И так, поехали — 8 классических способов сделать вашу документацию ненавистной для пользователя.
Структура не нужна
Пишите сплошным текстом, чтобы получилась «портянка». Все уже давным-давно освоили функцию Ctrl+F. Абзацы, разделы — это только отнимает время писателя. Кому надо, тот найдет.
Навигация ни к чему
Кстати, насчет Ctrl+F. В PDF или CHM форматах оно, к сожалению, работает, так что упорный и усердный пользователь скорее всего найдет нужную ему информацию. Но вот в онлайн-справке…
Онлайн руководство является набором HTML страниц, и функция ctrl+f будет работать только на открытой в данный момент странице. Сколько обычно страниц в мануалах? Удачи, дорогие пользователи.
Не добавляйте скриншоты и графику
Про то, что лучше один раз увидеть — это все байки. Наглядность для слабых. Если хотите, чтобы пользователи были достойны, научите их проходить через настоящие трудности. Никакой графики и скриншотов, и уж тем более пояснительных аннотаций.
Не публикуйте руководство на сайте
Если вы хотите, чтобы ваши пользователи испытывали к вам неприязнь, сделайте так, чтобы документацию было невозможно найти. Запрячьте мануал куда-нибудь очень далеко в подразделы сайта, а лучше вовсе забудьте его опубликовать. Пользователи, не сумевшие найти руководство, будут очень рады поделиться своими впечатлениями в поддержку.
Не интегрируйте документацию в ПО
Не лишайте пользователей наслаждения постоянно нажимать Alt+Tab, когда они будут работать с вашим продуктом. Не нужно поставлять свой продукт вместе со справочной документацией. Зачем, если она уже есть где-то на сайте.
В смысле контекстная справка не работает?
Сленг — это круто
Профдеформация — все мы ей страдаем, в той или иной степени. Ну, а что, зря страдаем что ли? Пусть клиенты по достоинству оценят — «Деплой проекта на рабочие инстансы выполняется исключительно тимлидом, строго после того, как все изменения были смерджены в мастер-ветку, и было выполнено ревью правок членом devops-команды уровня не ниже мидла»
Локализация?
— Слушай, а если наша компания поставляется на зарубежные рынки, наверное, было бы классно перевести документацию на востребованные языки? Ни в коем случае не делайте этого, ведь английский знают все и везде.
Грамматические ошибки
Настолько важная тема, что скажу серьезно. Всех. Безумно. Бесят. Ошибки. Перепроверьте документацию несколько раз перед релизом, отдайте на вычитку корректорам, в конце концов. Ошибки в документации очень существенно понижают репутацию компании и желание читать мануал дальше.
На этом всё. Конечно, ошибок мы видели больше, но в голову пришли самые частые и запоминающиеся.
Надеюсь, эта мини-статья хоть немного подняла настроение кому-либо.
P.S. Мемы с животными на тему документации.
