Сейчас многие компании спешно организуют удаленную работу для сотрудников. Этот процесс неизбежно сопряжен с составлением инструкций для технических слабых пользователей, а написание документов возлагается на ИТ-отделы. Сегодня я хочу предложить в помощь ИТ-специалистам свое мини-руководство по стилю технических инструкций.
[+] Сегодня в программе
Предпосылки
Многие вещи, очевидные системным администраторам и опытным пользователям, абсолютно непонятны людям, далеким от ИТ и привыкшим к опеке технических специалистов. Чем лучше написано руководство, тем понятнее оно будет конечным пользователям, что в свою очередь упрощает поддержку и снижает расходы на нее.
Я не планировал публиковать документ, но в одном из чатов Telegram зашел разговор по этой теме, и я указал на недостатки в инструкциях собеседников… В итоге я набросал черновик документа, а коллеги посчитали его полезным и предложили опубликовать для всех.
Ниже текущий текст документа и мои комментарии к нему.
Мини-руководство по стилю для технических инструкций
👉 Актуальная версия документа доступна на Google Docs.
Структура и оформление текста
- Структурируйте документ, используя заголовки и подзаголовки, чтобы упростить восприятие и навигацию.
- Добавляйте содержание в начале многостраничных документов.
- Применяйте нумерованные списки для пошаговых процедур.
- Ограничивайте процедуры 7-9 шагами, чтобы облегчить восприятие. Длинные процедуры разбивайте логически.
- Используйте разрывы страниц для отделения процедур друг от друга.
- Соблюдайте параллельную структуру в списках. Например, в этом списке все предложения начинаются с глаголов в повелительном наклонении, поэтому неправильно было бы начать этот пункт словами «Соблюдение параллельной структуры обязательно…».
- Не злоупотребляйте цветным шрифтом, особенно красным. Вместо целого предложения или абзаца достаточно выделить первое слово, например, «Важно!».
Язык
- Пишите инструкции понятным русским языком и не используйте сленг («виндовс», «винчестер» и пр. недопустимы).
- Обращайтесь непосредственно к читателю. Например, пишите «вы можете» вместо «пользователь может». Это помогает установить прямой контакт с читателем и позволяет избежать сухости в повествовании.
- Давайте четкие указания в инструкциях, используя глаголы в повелительном наклонении. Например, «откройте» и «перейдите», вместо «пользователь открывает» или «необходимо перейти».
- Избавляйтесь от лишних слов, не добавляющих ценности повествованию и тем более инструкциям. Например, в пошаговой процедуре вместо «После этого необходимо ввести» достаточно «Введите».
- Избегайте слишком длинных предложений, в которых могут потеряться читатели. Если ваше предложение содержит более 30 слов, разделите его на два, либо преобразуйте в маркированный список в случае, когда перечисляются однородные пункты.
- Проверяйте правописание программными средствами, но помните, что это не гарантирует отсутствия ошибок. Прочтите статью вслух для выявления стилистических недостатков и орфографических погрешностей.
Картинки
- Не перегружайте инструкции снимками экрана, чтобы читатели в них не путались. Необязательно сопровождать каждый шаг процедуры картинкой, и она совсем не нужна, если не добавляет ценности повествованию. Не забывайте, что следуя процедуре, читатель уже видит перед собой графический интерфейс программы или операционной системы.
- Избегайте добавления излишних графических элементов на картинках. Выделяйте только ключевые области картинок маркером, стрелками или прямоугольниками.
- Соблюдайте интуитивно понятную цветовую гамму графических элементов. Зеленый цвет обозначает правильное действие, красный цвет – неправильное.
Мои комментарии к документу
Первую версию своего руководства по стилям я опубликовал еще во времена конкурсов на OSZone, и даже предлагал один из вариантов в блоге для участников конкурса фишек Windows 8.1. В сегодняшней редакции некоторые тезисы переехали в другие разделы, потому что структура документа – это постоянный поиск идеала.
Профессиональные руководства по стилям легко могут превышать сотню страниц, за что их составителей люто ненавидят писатели:)
Эти документы описывают все возможные нюансы создания технической документации – от шрифтов и особенностей пунктуации до правил размещения графических элементов на картинках и примеров типовых выражений.
При этом требования могут варьироваться в зависимости от целевой аудитории. Например, для ИТ-специалистов и разработчиков допустим более технический язык, а для конечных пользователей программного продукта запрещен страдательный залог без необходимости.
Здесь я публикую базовую версию – самый минимум, умещающийся на одну страницу. Но, как это часто бывает со статьями блога, если вы подметите для себя один-два новых момента, я сочту свою цель достигнутой.
И, конечно, вы все это видели в моих статьях много раз, просто не придавали значения. Открыв любую из них, вы легко убедитесь, что я следую всем пунктам руководства.
Дискуссия
Я предлагаю обсудить, как новые реалии повлияли на ваш рабочий процесс. Например, у меня на текущем проекте была техническая возможность работы из дома, однако клиент требовал трудиться в офисе. Это требование сняли, а сотрудникам просто отдали домой их ПК и мониторы (у многих их либо нет, либо устройства не годятся для эффективной работы).
В комментариях расскажите:
- что изменилось в вашем рабочем или образовательном процессе
- какие сложности возникали и как вы с ними справлялись
- повысилась или снизилась эффективность вашей работы или учебы
О, руководства по стилю — любимая тема :) Кажется, я тут побывал во всех ролях: и как переводчик/технический писатель, и как автор руководства, и как редактор, контролирующий правильность его использования. Позвольте добавить один пункт, не особо очевидный для начинающих писателей, но заметно облегчающий чтение документа.
• Перечисляйте элементы интерфейса в том же порядке, в каком пользователь будет их искать и выбирать. Неправильно: Установите флажок «Включать» в группе «Действия при запуске» на вкладке «Общие».. Правильно: На вкладке «Общие» в группе «Действия при запуске» установите флажок «Включать».
Не могу говорить за всех писателей, но лично я никогда не испытывал ненависти к подробным руководствам. Наоборот, там можно почерпнуть что-то полезное, так как их обычно составляют грамотные люди. Бывали исключения, но редко. Что-то из разряда «наш продукт уникальный, поэтому в документации мы пишем не папка, а каталог».
Ну, и чтобы этот комментарий не был совсем уж офтопиком, отвечу на заданный Вадимом вопрос. У меня мало что изменилось в рабочем процессе — как работал из дома, так и работаю — только объем работы (и доход) заметно уменьшился.
Максим, ваш комментарий ожидался (возможно, он будет единственным :)
Да, порядок элементов — это очень правильный пункт (upd. добавил в документ). Я, кстати, иногда его не соблюдаю — когда заходит речь о параметре реестра в каком-то разделе, могу написать сначала параметр, потом раздел.
Более того, я накануне полистал одно из любимых руководств, там вообще запрещается упоминать названия элементов интерфейса без необходимости. Процедура идет с картинкой, и они пишут просто:
Без контекста выглядит странно / аскетично. Но когда весь документ в таком стиле, абсолютно нормально выходит.
Видна рука профессионала — никаких закладок и галочек :)
Я раздумывал над тем, включать ли в свой документ пункт о правильных названиях элементов интерфейса (в каком-то рук-ве для конкурсов он был, емнип). В итоге решил, что это лишнее для целевой аудитории в контексте текущих условий.
Отличная статья, спасибо.
По работе часто приходится писать инструкции и пояснения в локальную «википедию». В общем-то стараюсь соблюдать все перечисленные тут пункты. Особенно рьяно слежу за «простотой изложения» (не выношу все эти канцеляризмы вроде «с целью недопущения возникновения», «данный пользователь», «мною было проведено» и пр.
Моя слабость — картинки: никогда не делаю их в виде превьюшек, а только полноразмерными. Иначе чтение будет затруднено и внимание будет рассеиваться. В детстве по этой причине особенно недолюбливал книжки с отдельным блоком иллюстраций — нужно было «метаться» туда-сюда между текстом и картинками.
Кстати, очень нравится оформление статей у Technet Microsoft. Четкое структурирование (с оглавлением сбоку, класс!), важные абзацы выделены цветом, шрифт легкий sans-serif; а названия кнопок/файлов, с которыми производится действие, взяты полужирным.
https://i.imgur.com/FUDlOJt.png
Почти ничего, потому что несколько раз в месяц (по болезни или по семейным делам) работаю из дома. Всё отлажено.
Главная сложность — если откажет бесперебойник и/или компьютер перегрузится, то придется ехать в офис, так как на компьютере установлен BitLocker.
Примерно такая же (ну ладно, за счет того, что дома всё равно вольготнее себя чувствуешь, пусть будет 80% по сравнению с офисом).
Я раньше в блоге так делал из-за трафика (в т.ч. мобильного), но сейчас перестал — просто публикую в полный размер, а дальше уже масштабирование в браузере само работает.
Это Microsoft Docs теперь, но да, у них стало намного лучше чем было на TechNet и MSDN. И даже темную тему запилили по последней моде :)
В смысле нет пароля восстановления? Если политика настроена, он может храниться в AD DS, и следовательно администратор может передать его любым способом.
Спасибо за подборку. Вещи местами очевидные, но не всегда осознаваемые.
Утащил к себе.
Вообще документация это лютый батхерт, начиная с того что у меня есть ощущение что разработчикам и UI дизайнерам вообще насрать кто этим будет пользоваться, т.е. сам интерфейс часто противоречит кейсам по которым его используют. При хорошем интерфейсе как правило писание мануалов сводится к минимуму, уменьшаются выбросы СО2, улучшается настроение повышается аппетит… юзер сами зачастую сразу понимают как это будет работать.
Но хороших интерфейсов раз два и обчелся. Доходит до того что разработчики сами не могут объяснить как это все работает, вот последний диалог с Яндекс.музыкой вот закончился ничем, и я не знаю как объяснить домашним как правильно этим пользоваться чтобы ожидания от использования соответствовали действительности.
Другой пример — как красная тряпка — Apple — практически все знают как этим пользоваться, но по факту используется от силы половина реальных возможностей, инструкции никто не читал и даже не знают что она есть ( и кстати регулярно апдейтится) Зато стоит сказать в любом массовом чате чтобы получить лучи ненависти. Такое ощущение что сейчас времена, когда все вокруг не беические индивидуальности и это святое право — делать ущербные интерфейсы, а пусть вторые это документируют, а трети пытаются пользоваться ведя пальчиком по бумажке и по экрану. Уже не говоря про регулярные апдейты доки.
Да, осознание приходит, когда начинаешь примерять их к какому-нибудь гайду :)
Отчасти так и есть. Но даже хороший интерфейс может быть очень сложным в бизнес-приложениях, просто ввиду большого количества задач, которые они решают.
И если пользователь не может найти, как решить свою задачу, он лезет в документацию (а скорее — сразу долбит поддержку). И вот поддержка должна знать, где это описано. А если не описано, это уже может быть упущением составителей документации (в зависимости от требований к ней от продуктовой группы).
Структура и оформление текста.
— «Структурируйте документ», но не увлекайтесь. Если разбивать документ очень подробно, то объем текста в подзаголовке или даже главке может быть сведен до одного абзаца.
Считается нормальным для восприятия 4-5 глав (без литературы, перечня ссылок и проч.) по 3-4 параграфа/подглав в каждой главе. Более подробно система разбиения и классификации изложена в литературе для подготовки/составления методпособий и руководств для студентов педвузов;
— «Применяйте нумерованные списки…» — замечено, что тем, кому за 50 лучше воспринимают метки разбиения в виде цифр. Более молодые склонны к разделителям/нумераторам в виде точек (одна, две и т.д.) и сигнальных изображений;
— «Используйте разрывы страниц …» — не переусердствуйте. Большие разрывы не только раздувают объем, но и вызывают ощущение незаконченности предыдущего. Нормально — 1-2 интервала.
Дополнительно: не следует (тем более подробно) пояснять, что последует за несоблюдением/невыполнением конкретного пункта.
Однако, наиболее характерные ошибки лучше вынести в отдельный раздел и кратко пояснить, что надо сделать/предпринять.
Язык.
Хорошо бы для сотрудников иметь краткий словарь распространенных терминов и определений с картинками.
Картинки.
Не следует делать картинки большими. Вы вынуждаете читателя «скакать» по тексту для поиска описаний элементов на рисунке и для ориентации в них. Рисунки можно не подписывать (на усмотрение).
С другой стороны, мелкие и перегруженные изображения сложны для восприятия (тем более, если они черно-белые).
С уважением, OldFedor.
Любопытно. Но что вы будете делать, если целевая аудитория представлена различными возрастными группами?
Не соглашусь. В контексте это смотрится органично, а вы предлагаете это куда-то выносить, чтобы читатель прыгал туда-сюда.
Да, это необходимо, и такой список даже обязателен в большом руководстве (ака «Термины и определения»). Но такое часто выходит за рамки небольшого набора инструкций.
Это зависит от формата документа. Допустим, Word — это палка о двух концах: уменьшение масштаба картинки (чтобы органично смотрелось в процедуре) и наглядность (на мелкой плохо видно, а не все догадаются увеличить и рассмотреть).
Скриншоты тоже надо уметь делать, но это отдельное искусство, и вряд ли ЦА моего документа им хорошо владеет.
Хотя бы пару рекомендаций.
1. Используйте комбинированные картинки с частичным наложением, когда надо показать несколько окон.
2. Применяйте нумерацию элементов в порядке «слева направо, сверху вниз». Другими словами, если отмечаете элементы на картинке цифрами (1, 2, 3…), эти цифры всегда должны идти в определенном порядке, чтобы читатель не метался.
Вот пример моей картинки, где есть оба пункта, причем второй сделан неправильно :) Исправить такое можно только выносами цифр на тонких линиях (и да, формат таких выносов тоже прописывается в руководстве по стилю). Но я решил не заморачиваться настолько, потому что реально лучше от этого не стало бы в таком порядке действий в этом UI.
А вообще, картинки — беда документации. Потому что их приходится переделывать с каждым изменением UI, что существенно увеличивает затраты. Осознавшие это стремятся добавлять их только при необходимости.
Еще у меня в практике был забавный случай, когда заказчик постфактум потребовал изменить все стрелки на скриншотах с зеленых на красные (хотя ранее стиль был продемонстрирован в образцах и согласован). Оказалось, что на их дерьмовых мониторах зеленый цвет виден хуже красного. Писателю пришлось переделать / фотошопить, а заказчику — переплатить.
Точно, Docs. И темную тему, и версию на английском (но это не везде).
Пароль есть, хранится в AD DS, но все равно после перезагрузки его нужно вводить самому.
Гм… версия на английском исходная. Остальное — машинный перевод для всех новых доков. Какие-то переводятся людьми, но кмк это зависит от желаний и бюджета продуктовой группы. У Microsoft сейчас практически нет технических писателей, в Docs пишут ПГ — ПМы или разработчики.
В любом случае, русский перевод может отставать на месяцы, лучше его не смотреть.
Вадим, спасибо! Четко, конкретно и по делу скопировал к себе для работы.
Я бы еще рекомендовал в шапку «Мини-руководства» включить упоминание о ГОСТ 2.105-95 «ЕСКД. Общие требования к текстовым документам.» и ГОСТ 2.610-2006 «ЕСКД. Правила выполнения эксплуатационных документов.», а также на ГОСТ 7.31-2017 «СИБИД. Отчет о научно-исследовательской работе. Структура и правила оформления».
Как показывает практика многие «технические писатели» с удивлением узнают о существовании стандартов на текстовые документы.
Виталий, ГОСТы — это тоже руководства по стилям, конечно. Но в контексте этой статьи и целевой аудитории писателей и читателей они совершенно не нужны.
Однозначно в закладки.
Есть у меня рекомендации по оформлению презентаций. Так что этот пост в копилку.
1. Читал работать по 10-12 часов, вместо прежних 8-9.
2. сложности возникают только с одним «чудесным» продуктом под названием Skype for business. То звук пропадает, то звонок на мобильный клиент не приходит или приходит, но с диким опозданием, то не все могут подключиться к конференции, то ещё что-нибудь. В том же WhatsApp таких проблем нет и близко. Мобильный клиент — вообще отдельная песня.
3. эффективность оценить сложно. можно только сказать, что комфорт конечно повысился, а вот 10-12 часовой рабочий день радости не особо много доставляет.
А с чем конкретно связано увеличение рабочего дня? Недостаток персонала?