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

16.12.2013

Мы начинаем цикл статей, посвящённых вопросу возникновения ошибок при работе технического писателя и способах их устранения. Сегодня мы увидим описания четырёх самых распространённых ошибок.

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

Непонимание продукта или приложения

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

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

Повторение за экспертом по предмету.

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

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

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

Наша работа в качестве технических писателей состоит в том, чтобы переводить сложное и запутанное в то, что может понять каждый. Мы с вами представляем интересы Обычного Пользователя. Если вы чего-то не понимаете, будьте уверены, что и Обычный Пользователь ничего не поймёт. Никогда не повторяйте за ЭП дословно. Всегда требуйте разъяснений.

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

Заметьте, моя речь содержит краткое определение технического писательства:

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

И наконец, чтобы понять, что же такое «включить аварийку», перейдите по ссылке. Или, если у вас установлен Google toolbar, впишите в поисковую строку «define:abend».

Работа без плана.

Если вы работаете, не имея плана, вы создаёте лишнюю работу себе и другим. Без плана вы обнаружите, что новую информацию довольно сложно включить в документ по мере развития проекта или при изменении программного обеспечения. Фактически, без плана вы столкнётесь с множеством проблем. План должен включать:

• Список документов или глав, которые нужно написать. Обычно это:
  • описание продукта;
  • руководство по установке;
  • руководство по выбору конфигурации;
  • руководство пользователя или системного администратора;
  • другое;
• Условные обозначения и названия файлов, которые вы планируете использовать;
• Способ, которым документация попадёт к пользователю:
  • печатная копия;
  • лазерный диск;
  • закачка с сервера;
  • встроена в приложение;
• Способ, которым клиент будет обращаться к документации:
  • чтение печатной копии;
  • веб-страница или CD;
  • кнопка помощи в интерфейсе.

Когда вы начнёте понимать продукт или приложение, которое описываете, вам нужен план собственно документации:

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

Разнобой в названиях файлов.

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

Допустим, документация по сетевому приложению имеет название QDO. Сеть состоит из четырёх узлов с названиями BBB, QETO, IB и PBN, каждый из которых требует описания, руководства по установке, руководства по выбору конфигурации и руководства пользователя. IB и QETO также требуют справочник команд, а PNB имеет графический интерфейс и требует онлайн-справку по 25 пунктам, каждый из которых включает функции Добавить, Изменить, Удалить. Запутались? Если у вас нет единого метода присвоения названий, вы запутаетесь ещё больше.

Ваш метод должен иметь смысл и для вас, и для других. Например, вы решаете присваивать названия, которые включают имя узла, а затем имя документа. Так, название файла с описанием узла BBB будет выглядеть как bbb-опис.doc (или bbb-опис.fm), а руководство по установке для узла IB будет ib_устан.doc (или ib_устан.fm). Возможно, в имя не нужно включать название приложения, так как все файлы, относящиеся к данному приложению, будут храниться в отдельной папке. Если вы создаёте больший документ из нескольких маленьких, убедитесь, что и в названиях маленьких файлов нет разнобоя.

Предупреждение: не используйте «глава 1» (например, bbb_pd_глава1.fm) и т.д., так как порядок глав с развитием проекта изменится, и будут добавляться новые. Лучше используйте слова, обозначающие содержание этих глав, иначе в итоге названия будут выглядеть подобным образом:

bbb_опис_обложка.fm
bbb_опис_титул.fm
bbb_опис_содерж.fm
bbb_опис_вступление.fm
bbb_опис_глава2.fm
bbb_опис_глава3.fm
bbb_опис_глава1.fm
bbb_опис_глоссар.fm
bbb_опис_зад.облож.fm

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

Источник: Are You Making These Writing Mistakes?

Тэги: профессия, советы, стиль, эксперты