Всё для технического документирования
+7 (495) 001-40-42
Разработка технической документации
Курсы для технических писателей
Программное обеспечение

А вы допускаете эти ошибки? (Часть 4)

23.12.2013

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


Использование навороченных шаблонов

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

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

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

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

Вы должны создать шаблон для каждого типа документа, которые пишет ваша компания. Каждый шаблон должен конструироваться таким образом, чтобы быть простым в использовании. Если вы создаёте шаблоны в первый раз, рассчитывайте потратить около месяца на разработку первого шаблона и неделю или две на остальные. Будьте готовы потратить больше времени, если планируете добавлять в шаблоны стандартный текст. Вы, вероятно, обнаружите, что при написании первой версии документации приходится часто перенастраивать шаблон. Например, если стандартное текстовое поле в шаблонах составляет 6,5 дюйма, вы можете обнаружить, что команды слишком длинные и не помещаются. В этой ситуации вы можете решить, что документы, содержащие команды, должны иметь текстовое поле в 7,5 дюймов.

Для получения информации о разработке шаблонов, одно из первых, что вы можете сделать, это открыть любой справочник и изучить, как издатели его проработали. Обратите внимание на положение книжных элементов и элементов страницы, а затем попытайтесь воссоздать их в шаблонах. Я также рекомендую вам найти копию руководства The Chicago Manual of Style. Вы будете часто к нему обращаться

Когда вы станете опытным конструктором шаблонов, то обнаружите, что можете создать целый набор шаблонов менее чем за месяц. Если вы являетесь консультантом, то разработка шаблона – отличный навык, который вам очень пригодится!

Жёсткое кодирование оглавления, перекрёстных ссылок и нумерации

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

Частая табуляция

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

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

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

Отсутствие глоссария

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

(продолжение следует)

Источник: Are you making this writing mistakes?

Тэги: , , ,

< Вернуться к списку публикаций

Облако тегов