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

Теперь, когда вы познакомились с азами профессии и получили представление о том, с чего начинается работа над техническим документом, мы перейдём непосредственно к тем приёмам и методам, которыми вы будете активно пользоваться в своей работе. Многие формулировки вам вначале придётся воспринять «как факт» — их освоение потребует практики, другие же будут понятны и очевидны сразу.

Исходя из полученного ранее материала, вы, готовясь к написанию технического документа, уже смогли ответить на основные вопросы: на каком носителей он будет поставляться пользователям, к какой глобальной категории относится его ЦА (внешние, внутренние, широкий круг и т. д.) и, собственно, кто именно является его основной аудиторией. Теперь же вам нужно разработать то, на чём будет базироваться ваш документ — его структуру.

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

1. Формат и структура технического документа

Вся руководящая документация (пользователя, администратора и т. д.), все инструкции и документы, описывающие то или иное устройство или программу, по сути своей имеют общую структуру. Её материальным и видимым воплощением является оглавление документа. И именно с него вам и потребуется начать свою работу. Стоит отметить, что браться за написание руководства к программе можно лишь тогда, когда вы уже изучили её вдоль и поперёк. При попытке описать продукт параллельно с его изучением (по принципу: «что вижу — то пою»), вы с очень высокой (примерно 146%) вероятностью сядете в лужу или, в лучшем случае, сделаете всю работу два раза подряд, поскольку вам придется постоянно возвращаться по тексту назад, чтобы исправить всплывшие в ходе дальнейшего изучения программы нюансы или неточности.

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

1. Введение. Необязательный элемент, который может быть заменён аннотацией. Содержит краткую информацию о назначении программы, о содержании самого документа и указание его целевой аудитории. Занимает не более страницы. Для ПО и оборудования раздел выглядит одинаково.

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

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

4. Установка. Алгоритм действий по установке ПО на компьютер или установке в помещение и подключению к сети электронного оборудования.

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

6. Использование в работе. Часть, непосредственно посвящённая описанию приложения или устройства и работе с ним пользователя. Основной и самый крупный раздел документа.

7. Удаление. Для ПО в этом разделе описывается стандартная процедура удаления, для оборудования — демонтаж и условия утилизации, если они отличаются от типовых (вынести на помойку).

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

2. Формат и структура статьи. Канон и отступления от него

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

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

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

Статья-отчёт. Материал, посвящённый какому-либо мероприятию. Например, отчёт о проведённой некой ИТ-компанией конференции.

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

Статья-рассказ. В таком материале может быть повествование о чём и о ком угодно. О туристической поездке автора, о какой-то известной личности или историческом событии.

Статья-руководство. Эти статьи размещаются, как правило, на различных сетевых ресурсах, посвящённых IТ-тематике. Например, статья может содержать руководство по восстановлению повреждённых данных на жёстком диске.

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

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

Чтобы этого избежать, достаточно взять за основу (не за «прокрустово ложе», а именно за базу, которую можно в какой-то мере модифицировать) следующую структуру:

1. Вступление. Несколько общих слов о теме статьи, о том, что в ней содержится, о том, для кого и зачем вы её написали. Даже формулировка «сходил я давеча на конференцию, устроенную ООО "Рога и копыта", увидел много интересного и решил поделиться с другими» — вполне стоящие начало! Разумеется, для статьи в личный блог, а не для официального отчёта для компании-заказчика.

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

3. Основная часть. Здесь сосредоточен основной материал — анализ, сравнение, описание или повествование — в зависимости от типа статьи.

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

5. Заключение. Во всех типах статей, кроме аналитики, авторские выводы (именно личные авторские) пишутся тут. Вместо личного мнения автора могут быть его размышления о дальнейшем развитии темы. Например, рассказывая в статье про обстановку в городском ЖКХ, он может упомянуть о планах по изменению законодательства и перспективах по внедрению каких-либо новых технологий. Заключение присутствует в тексте не всегда, поскольку автор имеет право оставить все выводы и мысли «на совести читателя», не вплетая в материал свою субъективную оценку или мнение.

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

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