Редактирование собственного документа

04.10.2013

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

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

Моё же мнение заключается в том, что пользователи не должны ничего понимать. Они читают нашу документацию не для развлечения, и не для того, чтобы расширить собственное сознание, или улучшить свою способность мыслить. На самом деле пользователи вообще бы не читали нашу документацию. Техническая документация – это обычно не более, чем необходимое зло, что-то, что требуется пользователю, чтобы справиться с задачей так быстро и безболезненно, насколько это возможно. Наша работа – создать документацию простой и безболезненной для чтения. Она никогда не должна вызывать моменты замешательства, стресса, беспокойства или раздражения. Пользователь не должен никогда говорить «чего?»

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

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

В электронной версии документа:

• Проведите проверку орфографии в документе.
• Поищите в документе следующие частые недостатки (применимо к английскому языку):
  • Пассивный залог (ищите is, are, were, by и т.д.); замените на активный залог
  • Будущее время (ищите will); замените на настоящее время
  • Условное время (ищите ould); замените на настоящее время
  • Сокращения (ищите n’t и ‘ve); замените полными словами
  • Непараллельные конструкции (ищите списки); убедитесь, что первое слово каждого элемента списка – одного и того же типа (существительное, глагол)
  • Непрозрачный указатель (ищите «This»); убедитесь что, после этого «This» следует существительное, а не глагол
  • И/и; замените на «… или …. или оба»;
  • Запрещённые слова (ищите слова «kill», «abort» и все другие слова, которые ваша компания считает неуместными или неточными)
• Поищите в документе битые ссылки.
• Проведите ещё одну проверку орфографии.

После того, как вы завершили вышеперечисленные шаги, распечатайте документ и просмотрите на предмет следующих очевидных проблем:

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

Наконец, прочитайте весь документ, и представьте, что вы неквалифицированный пользователь; перепишите всё, что может показаться непонятным.

Источник: Editing Your Own Documentation

Тэги: анализ, профессия, редактирование, советы, форматирование