Александр Михайлов - Профессия Технический писатель, или Рыцари клавиатуры

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

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

Ссылки на различные места в документе можно делать перелинковкой, но в виде «кликабельных» слов вида «См. Раздел 3».

Также нужно избегать вставки внешних ссылок, так как у пользователя, имеющего только распечатку, может не быть возможности открыть ссылку на ПК (например, компьютер не имеет доступа в Интернет). Вместо ссылок можно делать сноски, в которых и размещать весь важный материал. Если объём информации по ссылке слишком велик, то его можно либо целиком внести в основной текст документа, либо все же сделать ссылку, но уже в явном виде, не заменяя текст ссылки словом. Например: www.google.ru.

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

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

• подобрать оптимальные для восприятия размеры и оформление шрифтов, так как у читателя нет возможности изменить их масштаб и начертание;

• соблюдать поля таким образом, чтобы части текста и рисунков не вылезали за них;

• использовать рисунки, которые нормально воспринимаются даже в чёрно-белом виде, так как зачастую в печать документ идёт в монохромном исполнении. При этом разноцветный и очень полезный график с экрана легко превращается в совершенно бесполезный набор кривых линий на бумаге. Исходя из этого, нужно планировать метод подачи графической составляющей документа: графиков, таблиц и рисунков;

• всю информацию, которую в другом случае можно дать в виде ссылок, здесь необходимо размещать прямо в документе в виде приложений (при большом объёме текста) или сносок (при маленьком объёме). Если необходима именно ссылка на сторонний ресурс — адрес ссылки пишется в явном виде.

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

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

Вообще, все читатели наших текстов условно делятся на три глобальные группы:

• сотрудник компании, в которой пишется документ;

• сторонние лица: пользователи, клиенты и т.д.;

• комиссии различного уровня, отвечающие за приём продукта в эксплуатацию.

Исходя из того, к какой группе относится ваша целевая аудитория, вам потребуется определить тот предельный объём информации, который вы имеете право изложить. Делается это, исходя из классификации документа по типам:

Документы для внутреннего пользования всегда являются собственностью компании и не могут носить копирайт отдельного человека, написавшего их. Они, как следует из названия, предназначены исключительно для сотрудников компании, и их попадание в руки посторонних крайне нежелательно. Эти документы могут храниться или в закрытых разделах корпоративного сайта или исключительно в локальной сети предприятия. Единственный вариант печатного вида подобных документов — брошюры для чтения сотрудниками на рабочем месте, не предназначенные для выноса за пределы офиса фирмы.

В текстах этого типа вы можете сообщать всю информацию о продукте, внутренних правилах фирмы, политику ценообразования, все тонкости разработок и технологий, словом — о чём только требуется. Изложение в этих документах должно быть предельно точным и буквальным, так как вам не нужно бояться «сболтнуть лишнего». В то же время, можно активно использовать устоявшийся в компании сленг, если таковой имеется — зачастую разработчики изобретают полуинопланетный язык, чтобы общаться между собой по поводу кода программы. Можете пойти им навстречу и тем же языком написать внутренние тексты для них — только «спасибо» скажут. Здесь можно не заботиться о защищённости технических ноу-хау и не бояться, что уникальные схемы, составляющие основные преимущества продукта перед конкурентами, уйдут «налево». Связано это отчасти с тем, что защита этих документов после их публикации — задача службы информационной безопасности предприятия.

Как следствие, лицо, ответственное за хранение и организацию доступа к таким документам, должно быть предельно внимательным: каждый сотрудник должен иметь доступ исключительно к тем документам, которые касаются лично его. Разработчики — к схемам БД, описанию кода, экономисты и финансисты — к данным о финансовом планировании и экономических показателях компании, бухгалтерия — к отчётам и правилам формирования премий и зарплаты. Если подобное разграничение не ввести и свалить всё в одну большую кучу — результат может быть плачевным. Например, младший секретарь Петя пороется в бумагах и увидит, что у старшего программиста Васи зарплата впятеро больше чем у него, и в состоянии обиженных чувств унесёт все до чего сможет дотянуться и опубликует всюду, на что фантазии хватит. Сотрудника, который организовал такое «общее» хранилище данных, бить будут долго и, возможно, ногами, но вред уже будет причинён.