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

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

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

Рис. 4. Флажки

• Название элемента, позволяющего переключаться между несколькими взаимоисключающими опциями — «переключатель». Имя переключателя — это название поля, объединяющего варианты положения переключателя (рис. 5).

Рис. 5. Переключатель «Ориентация»

• Полоса прокрутки — это полоса прокрутки, а не скролл, скроллинг или что-нибудь ещё.

• Описание последовательности действий по нажатию ряда экранных кнопок может осуществляться с помощью комбинации «—>». (Тире и символ «больше». Или просто ставьте стрелку из раздела Вставка → Символ.) Она помогает избежать многословного описания простого, как правило, процесса (например: Нажмите Пуск → Все программы → Калькулятор).

• Для устранения тавтологии в технической документации нужно не подбирать синонимы, а менять конструкцию фразы. Поскольку мы придерживаемся правила «одна сущность — один термин», мы не можем назвать его иначе, но и повторение одного и того же слова 20 раз на страницу текст не украсит. Оптимальными будут два метода:

1) По возможности термин заменяется на указатель на него: местоимения «его», «её» и т.д. Основной подводный камень здесь — однозначность. Вы должны следить, чтобы было всегда понятно, кого «его» мы имеем в виду.

2) Также термин можно заменить на более общий. Например, чтобы часто не писать название программы, можно иногда называть её «программа».

• Описание перехода по ссылке обычно делается с использованием одного из следующих клише (выделены полужирным):

1) Для скачивания дистрибутива перейдите по ссылке: *ссылка*;

2) ...дополнительную информацию можно получить по ссылке: *ссылка*.

• Кроме wiki-страниц, адрес ссылки всегда указывается в явном виде, например, www.mail.ru. Использовать слова-ссылки недопустимо!

• Для начала описания некой последовательности действий (эти последовательности ещё называют сценариями) удобно использовать такие клише: «чтобы установить программу / открыть папку, сделайте следующее / выполните следующие действия». Обратите внимание, что в начале клише не должно появляться слово «сделайте», т. к. оно используется во второй части фразы.

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

• Про мастера установки: Следуйте указаниям мастера установки... —не показаниям! Дело происходит не в суде. Глупая, но от этого не менее частая ошибка.

• Скобок не должно быть много, по возможности их лучше вовсе избегать.

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

• Названия компаний пишутся в кавычках, названия программ — без. Также важно обращать внимание, что к чему относится. Например, планировщик задач — относится к программе, функционал — тоже к программе. А вот служба поддержки относится к компании, а не к программе. И сама программа — это продукт компании. Например: «В службу поддержки компании "Microsoft" поступил вопрос от пользователя по функционалу программы MS Outlook».

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

• «Вода».Если текст напичкан лишними словами и сложными оборотами, это очень резко ухудшает его удобочитаемость и понятность. Текст должен быть максимально кратким!

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

Приступая к работе над любым текстом, важно заранее оценить его объём. Это связано со всевозможными ограничениями: размер статей для публикации в бумажных изданиях всегда строго регламентируется, объём новостей на сайте, по правилу хорошего тона, должен помещаться на экране без прокрутки, тексты в социальных сетях также после определённого объёма скрываются ссылкой вида «читать далее». Причин для ограничения размера текста существует множество, поэтому способность хотя бы приблизительно оценить размер своего будущего творения — очень важный навык для технического писателя. Разумеется, с точностью до знака угадывать ничего не придётся, но в пределах 10-15 тыс. знаков для больших (150 и более тысяч знаков), 3-5 тыс. знаков для средних (от 50 тыс. знаков) и 500-1000 знаков для маленьких (до 20-30 тыс. знаков) ориентироваться придётся. Если текст планируется менее 10 тысяч знаков, то его объём можно поправить по факту, чуть нарастив или урезав.

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