Редактирование собственного документа
04.10.2013
Данная заметка посвящена тому, каким образом можно редактировать документы, которые вы сами и писали.
Технические писатели подчас заблуждаются в том, что пользователь глуп. Я часто слышу, как технические писатели говорят нечто вроде «ну, если пользователь этого не может понять, то, возможно, он не на той работе!»
Моё же мнение заключается в том, что пользователи не должны ничего понимать. Они читают нашу документацию не для развлечения, и не для того, чтобы расширить собственное сознание, или улучшить свою способность мыслить. На самом деле пользователи вообще бы не читали нашу документацию. Техническая документация – это обычно не более, чем необходимое зло, что-то, что требуется пользователю, чтобы справиться с задачей так быстро и безболезненно, насколько это возможно. Наша работа – создать документацию простой и безболезненной для чтения. Она никогда не должна вызывать моменты замешательства, стресса, беспокойства или раздражения. Пользователь не должен никогда говорить «чего?»
Основная причина непонимания пользователя – небрежное писательство. Вы можете подумать, что это очевидно, но на самом деле я периодически вижу руководства пользователей, в которых есть орфографические, грамматические и пунктуационные ошибки, пробелы в логике, двусмысленности, пропущенные слова, неправильные термины, а также необычное форматирование, которые затрудняет навигацию. Даже лучшие писатели допускают временами такие ошибки.
Лучше, конечно, чтобы кто-то ещё просмотрел и отредактировал ваши документы, но вы можете успешно устранить многие проблемы в технических документах, выполнив нижеследующий список действий.
В электронной версии документа:
- Проведите проверку орфографии в документе.
- Поищите в документе следующие частые недостатки (применимо к английскому языку):
- Пассивный залог (ищите is, are, were, by и т.д.); замените на активный залог
- Будущее время (ищите will); замените на настоящее время
- Условное время (ищите ould); замените на настоящее время
- Сокращения (ищите n’t и ‘ve); замените полными словами
- Непараллельные конструкции (ищите списки); убедитесь, что первое слово каждого элемента списка – одного и того же типа (существительное, глагол)
- Непрозрачный указатель (ищите «This»); убедитесь что, после этого «This» следует существительное, а не глагол
- И/и; замените на «… или …. или оба»;
- Запрещённые слова (ищите слова «kill», «abort» и все другие слова, которые ваша компания считает неуместными или неточными)
- Поищите в документе битые ссылки.
- Проведите ещё одну проверку орфографии.
После того, как вы завершили вышеперечисленные шаги, распечатайте документ и просмотрите на предмет следующих очевидных проблем:
- Верхние и нижние колонтитулы (неправильное расположение элементов, неправильный текст)
- Заголовки (неправильное использование заглавных букв, неправильная иерархия)
- Нумерация страниц (неправильное расположение номера страницы, главы, начинающиеся на левой странице, римские числа, где должны быть арабские и наоборот)
- Содержание (неправильное выравнивание, отступы и иерархия)
- Формат таблиц (неправильные разрывы страниц, плохое выравнивание)
Наконец, прочитайте весь документ, и представьте, что вы неквалифицированный пользователь; перепишите всё, что может показаться непонятным.
Источник: Editing Your Own Documentation
Тэги: анализ, профессия, редактирование, советы, форматирование