Свежий номер №43 (420) / Милостивый государь, технический писатель
 
Дата публикации: 12.11.2001

Владислав Головач, vladislav.golovach@usethics.ru
Владимир Головач, golv@rarus.ru


 
<< Страница 1
Страница 2

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Замечание

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

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

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

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

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

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

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

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

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

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

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

Замечание

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

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

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

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

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

Замечание

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

FrameMaker 3 содержит практически все, в чем нуждается технический писатель (весь «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».




 
<< Страница 1
Страница 2


Владислав Головач
vladislav.golovach@usethics.ru
 


<< В поисках тленного стиля
Все материалы номера
Прочтите инструкцию >>