Наша команда много лет занимается разработкой программы для создания пользовательской документации. За это время мы столкнулись с бесчисленным множеством руководств, анализировали и проверяли документацию наших клиентов, создавали свою собственную документацию, добавляли новые фичи, например, шаблоны.

В общем, наш путь был долог и интересен, но он еще далеко не закончился. Сегодня хочу поделиться с вами опытом технического писателя и в немного (или много) сатирической форме предостеречь от классических, но очень серьезных ошибок при написании и публикации пользовательской документации, с которыми часто сталкивались в руководствах наших клиентов.

Если вы все-таки решились прочитать сие творение, то сразу скажем, лучший способ заставить пользователей ненавидеть вас и вашу документацию – не написать её. Правильно, зачем она нужна, ведь мы живем в 21-м веке, интерфейс у нас интуитивно понятен, каждый разберется какие кнопки за что отвечают, как успешно выполнять задачи и решать нетиповые проблемы, да?

(Автор пытается намекнуть, что пользовательская документация, даже в наше время все еще востребована, каким бы понятным и простым не был пользовательский интерфейс. Пользователи бывают разные и программы чаще всего бывают сложные. Конечно, вам, как разработчикам, кажется, что все просто. Это не так)

И так, поехали – 8 классических способов сделать вашу документацию ненавистной для пользователя.

Структура не нужна

Пишите сплошным текстом, чтобы получилась «портянка». Все уже давным-давно освоили функцию Ctrl+F. Абзацы, разделы – это только отнимает время писателя. Кому надо, тот найдет.

Навигация ни к чему

Кстати, насчет Ctrl+F. В PDF или CHM форматах оно, к сожалению, работает, так что упорный и усердный пользователь скорее всего найдет нужную ему информацию. Но вот в онлайн-справке…

Онлайн руководство является набором HTML страниц, и функция ctrl+f будет работать только на открытой в данный момент странице. Сколько обычно страниц в мануалах? Удачи, дорогие пользователи.

Не добавляйте скриншоты и графику

Про то, что лучше один раз увидеть — это все байки. Наглядность для слабых. Если хотите, чтобы пользователи были достойны, научите их проходить через настоящие трудности. Никакой графики и скриншотов, и уж тем более пояснительных аннотаций.

Не публикуйте руководство на сайте

Если вы хотите, чтобы ваши пользователи испытывали к вам неприязнь, сделайте так, чтобы документацию было невозможно найти. Запрячьте мануал куда-нибудь очень далеко в подразделы сайта, а лучше вовсе забудьте его опубликовать. Пользователи, не сумевшие найти руководство, будут очень рады поделиться своими впечатлениями в поддержку.

Не интегрируйте документацию в ПО

Не лишайте пользователей наслаждения постоянно нажимать Alt+Tab, когда они будут работать с вашим продуктом. Не нужно поставлять свой продукт вместе со справочной документацией. Зачем, если она уже есть где-то на сайте.

В смысле контекстная справка не работает? 

Сленг — это круто

Профдеформация – все мы ей страдаем, в той или иной степени. Ну а что, зря страдаем что ли? Пусть клиенты по достоинству оценят – «Деплой проекта на рабочие инстансы выполняется исключительно тимлидом, строго после того, как все изменения были смерджены в мастер-ветку, и было выполнено ревью правок членом devops-команды уровня не ниже мидла»

Локализация?

— Слушай, а если наша компания поставляется на зарубежные рынки, наверное, было бы классно перевести документацию на востребованные языки? Ни в коем случае не делайте этого, ведь английский знают все и везде.

Грамматические ошибки

Настолько важная тема, что скажу серьезно. Всех. Безумно. Бесят. Ошибки. Перепроверьте документацию несколько раз перед релизом, отдайте на вычитку корректорам, в конце концов. Ошибки в документации очень существенно понижают репутацию компании и желание читать мануал дальше.

На этом всё. Конечно, ошибок мы видели больше, но в голову пришли самые частые и запоминающиеся.

Надеюсь, эта мини-статья хоть немного подняла настроение кому-либо.

P.S. Мемы с животными на тему документации.