А вы допускаете эти ошибки? (часть 5)
Сегодня речь пойдет о мелочах, на которые зачастую не обращают внимание ни начинающие, ни более опытные технические писатели. В частности, об орфографии и правильном использовании времён.
Расположение информации в неправильном порядке
При описании пошаговых действий многие писатели первым делом сообщают пользователю, что делать, а уже потом – где это делать. На самом деле, вы должны сначала сообщить пользователю, где задача выполняется, и только потом, как она выполняется. Это называется «ориентирование пользователя».
Пример
Неправильно: Выберите стиль из меню Формат.
Правильно: В меню Формат выберите стиль.
В непроцедурных документах начните с большой картины, а затем сужайте её до деталей. Например, в описании продукта 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?
Тэги: советы, стиль, форматирование
- API
- DITA
- Flare
- HTML
- MadCap
- MS Word
- XML
- Алисса Фокс
- Марк Бейкер
- ПроТекст
- Том Джонсон
- анализ
- блоги
- веб-контент
- видеоролики
- единый источник
- изображения
- инструкции
- инструменты
- исследование
- качество контента
- командная работа
- конференции
- локализация/перевод
- минимализм
- навыки
- обучение
- опыт
- организация работы
- продвижение
- профессия
- редактирование
- роли
- советы
- стиль
- структурированное писательство
- теория документирования
- управление контентом
- форматирование
- форматы
- ценность контента
- эджайл
- эффективность
- юмор