Архивы: по дате | по разделам | по авторам

Милостивый государь, технический писатель

Архив

автор : Владислав Головач 12.11.2001

Глава первая.

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

Эти заметки выросли из врезки к статье одного из нас «Adobe FrameMaker. Солдат невидимого фронта», опубликованной в журнале «Курсив» (№6, 2000 год). В ней посильно анализируется качество труда технического писателя, работающего на русском языке в индустрии программирования.

Зачем нужны технические тексты

Что касается оперативных справок - с ними все ясно. Собственно говоря, одна из важнейших причин успеха Windows - прекрасно продуманная система их написания. Разработчикам стало проще писать оперативные справки, а пользователям - легче ими пользоваться. Эта система справок, существующая достаточно давно, практически не потеряла значения и сейчас, с появлением, например, HTML.

Однако справочная система не может служить заменой печатного руководства (в дальнейшем - Руководства). Это связано прежде всего с иными принципами восприятия печатного текста и текста справки на экране:

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

С печатным руководством, казалось бы, тоже все ясно: это учебник и/или справочник по программе (тут изначально заложено противоречие коня и трепетной лани, но этого мы сейчас касаться не будем). Однако часто не принимается во внимание важная функция Руководства, которую уместно назвать рекламной.

При беседе с потенциальным покупателем программного продукта и демонстрации достоинств последнего обязательно встает вопрос о Руководстве. Конечно же, это связано с подсознательным желанием клиента получить за свои деньги нечто материальное.

Наличие Руководства не отменяет нужду в собственно рекламных (информационных) материалах, но хотелось бы подчеркнуть, что Руководство само по себе должно играть роль важного рекламного материала. Качество Руководства - важный намек на качество программы.

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

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

Если продукт коробочный (то есть руководство спрятано внутри и до покупки не доступно), то рекламная роль руководства этим не умаляется.

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

Типичные особенности технических текстов

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

Второе: обычно объем этих текстов велик. В ходе правок объем неуклонно растет.

Руководство практически никогда не пишется (не переписывается) одним человеком. Обычно в его написании принимают участие многие, но «швы» для читателя должны быть незаметны. Другими словами, Руководство должно выглядеть единообразно.

Итак, мы подошли к третьей важнейшей особенности Руководства - единообразию. Эта особенность часто недооценивается.

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

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

Таким образом, требования к техническому тексту подчинены задаче достижения единообразия.

Нумеруется все - не только разделы, но и таблицы, рисунки, шаги процедур. Номер обязательно должен содержать видовую информацию (например, номер таблицы может быть таким: «Табл. 6-73», где «Табл.» - фиксированный текст, «6» - номер главы, а «73» - порядковый номер таблицы в главе). Эти номера должны расставляться автоматически (иначе в результате правок нумерация «поплывет»).

1-1. Текстовые потоки.

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

В принципе есть три способа борьбы с потерей фокуса внимания читателя:

Увеселение текста. Категорически не рекомендуется, так как противоречит основополагающему требованию единообразия.
Разделение единого текстового потока на множество потоков. Начало каждого потока - это точка, с которой можно возобновить чтение. Если технический писатель предусмотрел множество потоков (например, по несколько потоков на странице), то у читателя остается меньше шансов прекратить чтение.
Элегантная верстка. Вызывает у читателя столь желанное ощущение гладкости текста. Применительно к обсуждаемой теме верстка должна подчеркивать точки входа текстовых потоков и тем самым помогать читателю возобновить чтение.

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

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

Когда все пронумеровано, у читателя возникает ощущение, что учтено также все. Полезное ощущение на этапе «предпродажной обработки клиента».

Часто в нескольких разных местах Руководства требуется представлять один и тот же материал (например, определение, ограничение и т.п.). Буквальное повторение неудобно по следующим трем причинам:

Дезориентирует пользователя (не потенциального, а настоящего). Когда читатель встречается с уже освоенным материалом, он, разумеется, не уверен, что это один в один с тем, что встретилось ранее. Он хочет найти отличия от уже знакомого материала или убедиться, что их нет, но найти первое вхождение нелегко (ссылок нет).
Если читатель убеждается, что часть материала дублируется, то возникает разочарование: ощущение необязательности чтения.
Если писатель активно копирует материал, то возникают трудности, связанные с правкой Руководства: при внесении изменения может оказаться, что правке подлежат много разделов, не связанных друг с другом. При правке что-то обязательно будет пропущено.

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

Ссылки несут еще одну важную функцию: тогда, когда Руководство будет поставляться в электронном виде (например, в формате pdf или html), по этим ссылкам можно будет ходить! То есть когда наступит время Х, Руководство сразу будет содержать гиперссылки.

Важный аспект использования ссылок - указатель терминов. Указатель терминов - обязательный компонент любого англоязычного технического текста (от учебника до Руководства). Однако в кириллических текстах зачастую указателя либо нет совсем, либо он неполон.

Если указателя терминов нет, то ценность Руководства сокращается пропорционально квадрату его объема. Руководство без указателя терминов - нонсенс.

Иногда нужны также глоссарии, списки рисунков и пр. Все это, возможно, не очень нужно реально, но производит седуктивное действие на клиента.

Известны три способа разбиения единого текста на несколько потоков: врезки, таблицы и боковики (как в этих заметках). Для Руководств особенно ценны таблицы. Это обусловлено следующими их свойствами:

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

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

Великий и могучий

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

Замечание

Уместно вспомнить некоторые советские термины и насладиться их звучанием: ЭВМ (компьютер), АЦПУ (принтер), АЛУ (процессор), ЕСПД (не переводимо. По буквам: «единая система программной документации»).

Противоестественная любовь к аббревиатурам родились на заре советской власти (задолго до ЭВМ) и умерла вместе с ней.

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

Смело применяйте глаголы в повелительном наклонении - их пользователь любит. Вам следует использовать местоимения 2-го лица и действительный залог.

Не вредно не употреблять двойные отрицания. Избегайте (следует избегать) страдательного залога - тяжкого наследия советской квазинауки. Избегайте также (просто-таки рекомендуется избежание) отглагольных существительных.

Обширные абзацы и длинные перечисления (маркированные списки) утомляют читателя, ничего не давая ему взамен.

Разумеется, терминология должна быть стандартной.

К счастью, о русской компьютерной терминологии позаботился великий и могучий Микрософт ¹. Это не ирония: в советское время разнобой в терминологии был ужасающим. Лингвисты (кажется, общим числом два), сотрудники Микрософта из Дублина сделали невозможное: разные пользователи компьютеров могут говорить на русском языке и даже в определенных пределах понимать друг друга! Конечно, отдельные термины, введенные Микрософтом, поначалу вызывали у снобов отторжение. Однако невозможно не согласиться (хорошо сказано!), что весь комплект терминов, впервые появившийся в русских Руководствах этой компании, принят народом (что удивительно, практически целиком и без корректив).

1-2. Оценка качества.

Похоже, что оценить качество языка в техническом тексте довольно легко. Найдите процент вхождения слов

Который
Являться, производиться
Данное (в качестве прилагательного, а не существительного. Встречались тексты, в которых эти разные части речи употреблялись одновременно!)

Чем этих паразитов меньше, тем лучше.

[i42022]

1 (обратно к тексту) - При транслитерации этого названия лучше не отклоняться от традиции русского языка, зафиксированной, в частности, в словарях. Мы же не говорим «майкроскоп» и «майкроцефал».
2 (обратно к тексту) - А применять сноски (подстраничные и подтабличные) обычно имеет смысл: сноска - самостоятельный текстовый поток.
3 (обратно к тексту) - В ноябре издательство «Питер» выпускает замечательную книгу - Adobe FrameMaker 6.0, Учебный курс. Подготовка кириллических публикаций. Еще бы этой книге не быть замечательной, если мы сами ее и писали, и разрабатывали шаблоны верстки.

Над чем приходится работать техническому писателю

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

В последние годы на Западе активно обсуждается возможность одновременного создания Руководства и справочной системы (single-sourcing - «общие исходники»). Некоторые считают это кардинальным средством удешевления разработки, другие - несбыточной мечтой (заметим, что некоторые издательские системы изначально имеют средства хранения в одном документе нескольких содержательных слоев). Что касается отечественных условий, то вспомним дешевизну рабочего часа нашего технического писателя и отсутствие индустрии создания программного обеспечения (в лучшем случае мы находимся на этапе мануфактур). Общие исходники для всей кириллической документации появятся никак не раньше, чем окажутся

Полезный совет

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

экономически выгодными.

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

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

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

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

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

Рекламные материалы, даже включаемые в состав Руководства, должны быть написаны более живо, более свободно. И верстка их должна быть более «свободной». Рекламную главу в составе Руководства допустимо верстать так, чтобы она отличалась от остального, технического материала. Например, его можно подать при помощи боковиков.

Искусство верстки

Верстка материала Руководств имеет особенности.

Так как Руководство нужно часто переиздавать, средства верстки должны обеспечивать ее автоматизацию. Новое издание обычно требует внесения нескольких относительно небольших исправлений в разные участки текста. Система должна предоставлять гарантию, что в результате верстка не «поплывет». Например, если применяются подстраничные сноски ², а система верстки их прямо не поддерживает (их приходится делать вручную - например, такова ситуация в PageMaker или QuarkXPress), то после правки нужно просмотреть весь последующий текст и подправить «съехавшие» сноски.

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

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

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

Замечание

Роль верстки чисто вспомогательная, все, что от нее требуется - раскрытие содержания. Никакой «самоценной» роли верстка не имеет.

Чем лучше содержание, тем выше роль верстки. Дурная верстка способна ухудшить восприятие хорошего материала.

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

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

Есть еще несколько вопросов, важных с точки зрения организации труда. Ясно, что дополнения в указатель терминов и глоссарий, а также перекрестные ссылки верстальщик добавлять не будет. Точнее говоря, все это вообще добавляться не должно: это должно быть неотъемлемой частью материала. Таким образом, шаблон, с которым работают технические писатели, должен определять свойства перекрестных ссылок и входов указателя терминов; в противном случае система не может гарантировать единообразия.

На чём работать техническому писателю

Выше были сформулированы некоторые требования к системе верстки для технических писателей. В нашей стране обычно особых колебаний нет: вся работа выполняется в Microsoft Word. Именно эта программа (не являясь в полном смысле системой верстки - например, она предполагает монохромную печать) содержит многое из того, что требуется техническому писателю.

Но недостатки этой программы также велики. Главное - невозможность работы с объемными документами. С ними MS Word работает ненадежно, что хорошо известно всем заинтересованным лицам. Кроме того, нелишне отметить и другие менее важные (на фоне главного) недостатки.

Невозможно задать стили и клише для ссылок (например, потребовать, чтобы не было ссылок вида «а про это посмотрите на стр. NN»). Нельзя задать стили для указателей.

Перекрестные ссылки работают ненадежно. Дело в том, что для перекрестных ссылок опять-таки применен аппарат закладок. Эту ненадежность проще всего показать на примере.

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

Замечание

MS Word состоит не только из одних недостатков. Совершенно замечательна в нем возможность полноценного программирования, которым можно обойти практически все ограничения, накладываемые этой системой на технического писателя (даже трудности работы с большими документами). Другими словами, в принципе реально запрограммировать все, что изначально отсутствует в MS Word, но в чем нуждается технический писатель. Дело за малым?

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

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

Наконец, шаблоны MS Word не позволяют управлять некоторыми важными элементами оформления Руководства. Например, невозможно зафиксировать ни местоположение, ни содержимое колонтитулов. Это мешает достижению единообразия.

Гораздо больше готовых возможностей для технического писателя предоставляют такие системы верстки, как FrameMaker (компания Adobe) и LaTex (автор Лесли Лампорт, общественное достояние). FrameMaker - это инструмент, с помощью которого в мире (но не в России) делается основная масса технических публикаций. LaTex безумно сложен, хотя обладает мощными возможностями программирования.

Замечание

Если затронутая проблематика вас заинтересовала, вы можете найти в Интернете массу англоязычных публикаций по этой теме. Очень качественный русскоязычный сайт находится по адресу. См. также. Прекрасный, частично аннотированный список ресурсов по всем аспектам технического писательства (на английском языке).

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

Однако выход есть. Пакет Орфо 2000 (и более ранние версии) позволяет вставлять в кириллические тексты в окнах MS Word мягкие переносы (то есть переносы, невидимые до тех пор, пока в них не возникает нужда). В свою очередь, FrameMaker позволяет импортировать сформатированный текст из MS Word. Таким образом, возможна следующая технология разработки технической документации.

Черновики пишутся в MS Word, обрабатываются пакетом Орфо (замечу, что и в части орфографического контроля автономный пакет Орфо удобнее, чем та старая версия, которая встроена в MS Word). Затем черновики (с проверенной орфографией и содержащие мягкие переносы) переносятся в среду FrameMaker (например, при помощи буфера обмена), где практически сразу приобретают нужное оформление за счет заранее разработанных мощных и всеобъемлющих шаблонов. Черновики более не нужны: исходные файлы поддерживаются в формате FrameMaker. Правда, названия абзацных стилей в MS Word и FrameMaker должны буквально совпадать: именно благодаря этому перенесенные абзацы немедленно приобретают нужное оформление.

Разумеется, если нужна правка одного изолированного абзаца, черновик можно и не писать. Можно отредактировать текст непосредственно в среде FrameMaker (где редакторские средства вообще-то хороши, но при работе с кириллицей есть определенные неудобства).

При необходимости передачи файлов документации на другие компьютеры используется формат pdf (с которым FrameMaker, в отличие от MS Word, работает надежно) или rtf (при переводе в этот формат FrameMaker обычно упрощает верстку; тем не менее абзацные стили сохраняются).

1-3. Трудности чтения.

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

Трудности чтения связаны с тем, что название этой компании - испанское, а не английское слово.

Итак, следуя объяснению Колина Грина (CGreen@Illuminet.com) и нескольких других корреспондентов, потрудившихся ответить на наш вопрос: «ah - doe - bee». Произносится быстро с небольшим ударением на среднем слоге. «Ah» - открывайте рот, как для показа доктору. «Doe» как в слове «dough» (тесто). «Be» как у Шекспира: «To be or not to be».