Сейчас многие компании спешно организуют удаленную работу для сотрудников. Этот процесс неизбежно сопряжен с составлением инструкций для технически слабых пользователей, а написание документов возлагается на ИТ-отделы. Сегодня я хочу предложить в помощь ИТ-специалистам свое мини-руководство по стилю технических инструкций.

[+] Сегодня в программе

Предпосылки

Многие вещи, очевидные системным администраторам и опытным пользователям, абсолютно непонятны людям, далеким от ИТ и привыкшим к опеке технических специалистов. Чем лучше написано руководство, тем понятнее оно будет конечным пользователям, что в свою очередь упрощает поддержку и снижает расходы на нее.

Я не планировал публиковать документ, но в одном из чатов Telegram зашел разговор по этой теме, и я указал на недостатки в инструкциях собеседников… В итоге я набросал черновик документа, а коллеги посчитали его полезным и предложили опубликовать для всех.

Ниже текущий текст документа и мои комментарии к нему.

Мини-руководство по стилю для технических инструкций

👉 Актуальная версия документа доступна на Google Docs.

Структура и оформление текста

• Структурируйте документ, используя заголовки и подзаголовки, чтобы упростить восприятие и навигацию.
• Добавляйте содержание в начале многостраничных документов.
• Применяйте нумерованные списки для пошаговых процедур.
• Ограничивайте процедуры 7-9 шагами, чтобы облегчить восприятие. Длинные процедуры разбивайте логически.
• Используйте разрывы страниц для отделения процедур друг от друга.
• Соблюдайте параллельную структуру в списках. Например, в этом списке все предложения начинаются с глаголов в повелительном наклонении, поэтому неправильно было бы начать этот пункт словами «Соблюдение параллельной структуры обязательно…».
• Не злоупотребляйте цветным шрифтом, особенно красным. Вместо целого предложения или абзаца достаточно выделить первое слово, например, «Важно!».

Язык

• Пишите инструкции понятным русским языком и не используйте сленг («виндовс», «винчестер» и пр. недопустимы).
• Обращайтесь непосредственно к читателю. Например, пишите «вы можете» вместо «пользователь может». Это помогает установить прямой контакт с читателем и позволяет избежать сухости в повествовании.
• Давайте четкие указания в инструкциях, используя глаголы в повелительном наклонении. Например, «откройте» и «перейдите», вместо «пользователь открывает» или «необходимо перейти».
• Избавляйтесь от лишних слов, не добавляющих ценности повествованию и тем более инструкциям. Например, в пошаговой процедуре вместо «После этого необходимо ввести» достаточно «Введите».
• Избегайте слишком длинных предложений, в которых могут потеряться читатели. Если ваше предложение содержит более 30 слов, разделите его на два, либо преобразуйте в маркированный список в случае, когда перечисляются однородные пункты.
• Проверяйте правописание программными средствами, но помните, что это не гарантирует отсутствия ошибок. Прочтите статью вслух для выявления стилистических недостатков и орфографических погрешностей.

Картинки

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

Мои комментарии к документу

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

Профессиональные руководства по стилям легко могут превышать сотню страниц, за что их составителей люто ненавидят писатели:)

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

При этом требования могут варьироваться в зависимости от целевой аудитории. Например, для ИТ-специалистов и разработчиков допустим более технический язык, а для конечных пользователей программного продукта запрещен страдательный залог без необходимости.

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

И, конечно, вы все это видели в моих статьях много раз, просто не придавали значения. Открыв любую из них, вы легко убедитесь, что я следую всем пунктам руководства.

Дискуссия

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

В комментариях расскажите:

• что изменилось в вашем рабочем или образовательном процессе
• какие сложности возникали и как вы с ними справлялись
• повысилась или снизилась эффективность вашей работы или учебы