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

25.12.2013

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

Расположение информации в неправильном порядке

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

Пример

Неправильно: Выберите стиль из меню Формат.

Правильно: В меню Формат выберите стиль.

В непроцедурных документах начните с большой картины, а затем сужайте её до деталей. Например, в описании продукта BBB вы бы могли начать с описания QDO. Затем вы должны описать отношения узла BBB с QDO и его связи с другими узлами в сети. Каждая глава начинается с краткого резюме содержания главы, как показано на следующей «цитате» из первой главы несуществующего описания продукта QDO узла BBB:

Узел BBB управляет связью между четырьмя узлами сети QDO. Четыре узла:

• BBB

• QETO

• IB

• PBN

В данной главе описывается сеть QDO, и представлен обзор функций четырех узлов.

Плохая орфография

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

Будущее время

Неопытные авторы часто описывают реакцию приложения на пользовательский запрос в будущем времени. Например, они могли бы написать: «Когда вы нажмёте Enter, появится предупреждающее сообщение»» В технической документации ничего не происходит в будущем! Будущее время вызывает беспокойство у читателя. Когда сообщение появится? А что делать, если не появится?

Всегда пишите в настоящем времени: «Когда вы нажимаете Enter, появляется предупреждающее сообщение».

Может быть, вы говорите себе: «Ну, было бы прекрасно, если бы наши предупреждающие сообщения появлялись менее чем за десять секунд. Но здесь определенно требуется будущее время!» Неправильно. В такой ситуации вы должны написать: «Через десять секунд после нажатия Enter на экране появляется предупреждающее сообщение». А еще лучше, опишите это как один из шагов процедуры:

1. Нажмите клавишу Enter. Через десять секунд появляется предупреждающее сообщение.

Сослагательное наклонение

Я бы не стал говорить об этой проблеме, если б никогда с ней не сталкивался, хотя это случается довольно редко. Использование условного наклонения может встречаться в документах, которые написаны до полного завершения приложения – когда команда разработчиков не совсем уверена, как приложение будет реагировать на ввод пользователя. Например, специалист может сказать вам: «Когда пользователь нажимает клавишу Enter, на экране должно появиться предупреждающее сообщение». Пока вам не скажут обратного, вы должны полагать, что предупреждения на самом деле появляются. Конечно, иногда нужно обращаться к специалисту, чтобы убедиться, что приложение отвечает, как описано.

Дружеский тон

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

Непараллельная структура маркированных списков

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

Неопределенная пунктуация маркированных списков

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

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

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

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

Тэги: советы, стиль, форматирование