Одними из самых распространённых типов технической документации являются инструкции или руководства. Так вот, с ними связана постоянная дилемма. Кому поручить написание инструкции - функциональному эксперту (он же разработчик или инженер) или же техническому писателю?

Попробуем разобраться на типичном примере.

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

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

Большая осведомлённость о продукте может оказать обратный эффект. С точки зрения функционального эксперта, в составленной им инструкции всё предельно ясно и понятно. Документ содержит только нужную информацию. Но помним, что тема касается инструкций и руководств. Перечисленные типы документов могут быть подготовлены для “технарей” (технических специалистов) и “нетехнарей” (конечных пользователей).

Вариант с подготовкой инструкции экспертом для технических специалистов, хоть и с натяжкой, но всё-таки имеет право на существование. Но в случае “пользовательской” инструкции привлечение функционального эксперта вряд ли будет хорошей идеей.

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

Привлечение техписателей в таких случаях является лучшим вариантом.

Технические писатели могут “свежим” взглядом осмотреть продукт. Им проще “вжиться” в роль пользователя. Да, техписатели в процессе исследований глубоко погружаются в продукт и в конце концов значительно повышают уровень экспертизы касательно этого продукта. Но при этом сохраняется отстранённость от погружение именно в технические детали, которые обычному пользователю могут быт просто неинтересны.

Чаще всего пользователям требуются детали “нетехнического” характера и “человеческая” формулировка мыслей в документе. Ведь как ни крути, техписатели всё-таки писатели. И они умеют излагать мысли понятным языком, писать просто о сложном.

Разумеется, нельзя всех обстричь под одну гребёнку.

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

В итоге мысль заметки такая: если вопрос обозначенный вначале касается пользовательской инструкции, то намного эффективнее её подготовит технический писатель. Если же речь идёт о руководстве администратора, то здесь может справиться и разработчик. Хотя всё-таки каждый должен заниматься своим делом. Разработчики и инженеры создают продукты, а техписатели рассказывают, как работать с этими продуктами.