Вадим Стеркин

  • Главная
  • Windows
  • SSD
  • Программы
  • Разное
  • Об авторе
Вы тут: Главная → Сообщество → Мини-руководство по стилю технических инструкций

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

Рубрики: Сообщество Обновлено: 22.04.2020 комментариев 17

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

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

  • Предпосылки
  • Мини-руководство по стилю для технических инструкций
    • Структура и оформление текста
    • Язык
    • Картинки
  • Мои комментарии к документу
  • Дискуссия

Предпосылки

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

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

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

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

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

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

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

Язык

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

Картинки

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

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

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

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

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

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

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

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

Дискуссия

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

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

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

Метки: WordPress

Об авторе

Вадим - владелец этого блога, и почти все записи здесь вышли из-под его пера. Подробности о блоге и авторе здесь.

Вас также может заинтересовать:

  • Как создаются записи этого блога
← Поддержите меня подпиской или донатом!
Итоги опроса читателей о версии Windows, типе накопителя и свободном пространстве →
Telegram logo

Я в Telegram

Подпишитесь на канал и читайте интересные записи чаще! Есть вопросы? Задайте их в чате.

комментариев 17

↓
  1. Maxim

    31.03.2020 в 16:39

    О, руководства по стилю — любимая тема :) Кажется, я тут побывал во всех ролях: и как переводчик/технический писатель, и как автор руководства, и как редактор, контролирующий правильность его использования. Позвольте добавить один пункт, не особо очевидный для начинающих писателей, но заметно облегчающий чтение документа.

    • Перечисляйте элементы интерфейса в том же порядке, в каком пользователь будет их искать и выбирать. Неправильно: Установите флажок «Включать» в группе «Действия при запуске» на вкладке «Общие».. Правильно: На вкладке «Общие» в группе «Действия при запуске» установите флажок «Включать».

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

    Ну, и чтобы этот комментарий не был совсем уж офтопиком, отвечу на заданный Вадимом вопрос. У меня мало что изменилось в рабочем процессе — как работал из дома, так и работаю — только объем работы (и доход) заметно уменьшился.

    Ваша оценка: Thumb up Thumb down 0
    • Vadim Sterkin

      31.03.2020 в 18:56

      Максим, ваш комментарий ожидался (возможно, он будет единственным :)

      Да, порядок элементов — это очень правильный пункт (upd. добавил в документ). Я, кстати, иногда его не соблюдаю — когда заходит речь о параметре реестра в каком-то разделе, могу написать сначала параметр, потом раздел.

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

      In Main, open Rates.

      Без контекста выглядит странно / аскетично. Но когда весь документ в таком стиле, абсолютно нормально выходит.

      Maxim: Правильно: На вкладке «Общие» в группе «Действия при запуске» установите флажок «Включать».

      Видна рука профессионала — никаких закладок и галочек :)

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

      Ваша оценка: Thumb up Thumb down 0
  2. Матвей Солодовников

    31.03.2020 в 19:53

    Отличная статья, спасибо.

    По работе часто приходится писать инструкции и пояснения в локальную «википедию». В общем-то стараюсь соблюдать все перечисленные тут пункты. Особенно рьяно слежу за «простотой изложения» (не выношу все эти канцеляризмы вроде «с целью недопущения возникновения», «данный пользователь», «мною было проведено» и пр.

    Моя слабость — картинки: никогда не делаю их в виде превьюшек, а только полноразмерными. Иначе чтение будет затруднено и внимание будет рассеиваться. В детстве по этой причине особенно недолюбливал книжки с отдельным блоком иллюстраций — нужно было «метаться» туда-сюда между текстом и картинками.

    Кстати, очень нравится оформление статей у Technet Microsoft. Четкое структурирование (с оглавлением сбоку, класс!), важные абзацы выделены цветом, шрифт легкий sans-serif; а названия кнопок/файлов, с которыми производится действие, взяты полужирным.

    https://i.imgur.com/FUDlOJt.png

    что изменилось в вашем рабочем или образовательном процессе

    Почти ничего, потому что несколько раз в месяц (по болезни или по семейным делам) работаю из дома. Всё отлажено.

    какие сложности возникали и как вы с ними справлялись

    Главная сложность — если откажет бесперебойник и/или компьютер перегрузится, то придется ехать в офис, так как на компьютере установлен BitLocker.

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

    Примерно такая же (ну ладно, за счет того, что дома всё равно вольготнее себя чувствуешь, пусть будет 80% по сравнению с офисом).

    Ваша оценка: Thumb up Thumb down 0
    • Vadim Sterkin

      01.04.2020 в 13:47

      Матвей Солодовников: Моя слабость — картинки: никогда не делаю их в виде превьюшек, а только полноразмерными. Иначе чтение будет затруднено и внимание будет рассеиваться.

      Я раньше в блоге так делал из-за трафика (в т.ч. мобильного), но сейчас перестал — просто публикую в полный размер, а дальше уже масштабирование в браузере само работает.

      Матвей Солодовников: Кстати, очень нравится оформление статей у Technet Microsoft.

      Это Microsoft Docs теперь, но да, у них стало намного лучше чем было на TechNet и MSDN. И даже темную тему запилили по последней моде :)

      Матвей Солодовников: Главная сложность — если откажет бесперебойник и/или компьютер перегрузится, то придется ехать в офис, так как на компьютере установлен BitLocker.

      В смысле нет пароля восстановления? Если политика настроена, он может храниться в AD DS, и следовательно администратор может передать его любым способом.

      Ваша оценка: Thumb up Thumb down 0
  3. Джонни

    31.03.2020 в 20:16

    Спасибо за подборку. Вещи местами очевидные, но не всегда осознаваемые.
    Утащил к себе.

    Вообще документация это лютый батхерт, начиная с того что у меня есть ощущение что разработчикам и UI дизайнерам вообще насрать кто этим будет пользоваться, т.е. сам интерфейс часто противоречит кейсам по которым его используют. При хорошем интерфейсе как правило писание мануалов сводится к минимуму, уменьшаются выбросы СО2, улучшается настроение повышается аппетит… юзер сами зачастую сразу понимают как это будет работать.

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

    Другой пример — как красная тряпка — Apple — практически все знают как этим пользоваться, но по факту используется от силы половина реальных возможностей, инструкции никто не читал и даже не знают что она есть ( и кстати регулярно апдейтится) Зато стоит сказать в любом массовом чате чтобы получить лучи ненависти. Такое ощущение что сейчас времена, когда все вокруг не беические индивидуальности и это святое право — делать ущербные интерфейсы, а пусть вторые это документируют, а трети пытаются пользоваться ведя пальчиком по бумажке и по экрану. Уже не говоря про регулярные апдейты доки.

    Ваша оценка: Thumb up Thumb down 0
    • Vadim Sterkin

      01.04.2020 в 13:50

      Джонни: Вещи местами очевидные, но не всегда осознаваемые.

      Да, осознание приходит, когда начинаешь примерять их к какому-нибудь гайду :)

      Джонни: При хорошем интерфейсе как правило писание мануалов сводится к минимуму, уменьшаются выбросы СО2, улучшается настроение повышается аппетит… юзер сами зачастую сразу понимают как это будет работать.

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

      И если пользователь не может найти, как решить свою задачу, он лезет в документацию (а скорее — сразу долбит поддержку). И вот поддержка должна знать, где это описано. А если не описано, это уже может быть упущением составителей документации (в зависимости от требований к ней от продуктовой группы).

      Ваша оценка: Thumb up Thumb down 0
  4. OldFedor

    01.04.2020 в 16:17

    Структура и оформление текста.
    — «Структурируйте документ», но не увлекайтесь. Если разбивать документ очень подробно, то объем текста в подзаголовке или даже главке может быть сведен до одного абзаца.
    Считается нормальным для восприятия 4-5 глав (без литературы, перечня ссылок и проч.) по 3-4 параграфа/подглав в каждой главе. Более подробно система разбиения и классификации изложена в литературе для подготовки/составления методпособий и руководств для студентов педвузов;
    — «Применяйте нумерованные списки…» — замечено, что тем, кому за 50 лучше воспринимают метки разбиения в виде цифр. Более молодые склонны к разделителям/нумераторам в виде точек (одна, две и т.д.) и сигнальных изображений;
    — «Используйте разрывы страниц …» — не переусердствуйте. Большие разрывы не только раздувают объем, но и вызывают ощущение незаконченности предыдущего. Нормально — 1-2 интервала.
    Дополнительно: не следует (тем более подробно) пояснять, что последует за несоблюдением/невыполнением конкретного пункта.
    Однако, наиболее характерные ошибки лучше вынести в отдельный раздел и кратко пояснить, что надо сделать/предпринять.

    Язык.
    Хорошо бы для сотрудников иметь краткий словарь распространенных терминов и определений с картинками.

    Картинки.
    Не следует делать картинки большими. Вы вынуждаете читателя «скакать» по тексту для поиска описаний элементов на рисунке и для ориентации в них. Рисунки можно не подписывать (на усмотрение).
    С другой стороны, мелкие и перегруженные изображения сложны для восприятия (тем более, если они черно-белые).

    С уважением, OldFedor.

    Ваша оценка: Thumb up Thumb down 0
  5. Vadim Sterkin

    02.04.2020 в 11:09

    OldFedor: — «Применяйте нумерованные списки…» — замечено, что тем, кому за 50 лучше воспринимают метки разбиения в виде цифр. Более молодые склонны к разделителям/нумераторам в виде точек (одна, две и т.д.) и сигнальных изображений;

    Любопытно. Но что вы будете делать, если целевая аудитория представлена различными возрастными группами?

    OldFedor: Дополнительно: не следует (тем более подробно) пояснять, что последует за несоблюдением/невыполнением конкретного пункта.
    Однако, наиболее характерные ошибки лучше вынести в отдельный раздел и кратко пояснить, что надо сделать/предпринять.

    Не соглашусь. В контексте это смотрится органично, а вы предлагаете это куда-то выносить, чтобы читатель прыгал туда-сюда.

    OldFedor: Хорошо бы для сотрудников иметь краткий словарь распространенных терминов и определений с картинками.

    Да, это необходимо, и такой список даже обязателен в большом руководстве (ака «Термины и определения»). Но такое часто выходит за рамки небольшого набора инструкций.

    OldFedor: Не следует делать картинки большими. Вы вынуждаете читателя «скакать» по тексту для поиска описаний элементов на рисунке и для ориентации в них.

    Это зависит от формата документа. Допустим, Word — это палка о двух концах: уменьшение масштаба картинки (чтобы органично смотрелось в процедуре) и наглядность (на мелкой плохо видно, а не все догадаются увеличить и рассмотреть).

    Скриншоты тоже надо уметь делать, но это отдельное искусство, и вряд ли ЦА моего документа им хорошо владеет.

    Ваша оценка: Thumb up Thumb down 0
    • Lecron

      02.04.2020 в 14:49

      Vadim Sterkin: Скриншоты тоже надо уметь делать, но это отдельное искусство, и вряд ли ЦА моего документа им хорошо владеет.

      Хотя бы пару рекомендаций.

      Ваша оценка: Thumb up Thumb down 0
      • Vadim Sterkin

        05.04.2020 в 10:52

        Lecron: Хотя бы пару рекомендаций.

        1. Используйте комбинированные картинки с частичным наложением, когда надо показать несколько окон.

        2. Применяйте нумерацию элементов в порядке «слева направо, сверху вниз». Другими словами, если отмечаете элементы на картинке цифрами (1, 2, 3…), эти цифры всегда должны идти в определенном порядке, чтобы читатель не метался.

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

        А вообще, картинки — беда документации. Потому что их приходится переделывать с каждым изменением UI, что существенно увеличивает затраты. Осознавшие это стремятся добавлять их только при необходимости.

        Еще у меня в практике был забавный случай, когда заказчик постфактум потребовал изменить все стрелки на скриншотах с зеленых на красные (хотя ранее стиль был продемонстрирован в образцах и согласован). Оказалось, что на их дерьмовых мониторах зеленый цвет виден хуже красного. Писателю пришлось переделать / фотошопить, а заказчику — переплатить.

        Ваша оценка: Thumb up Thumb down +1
  6. Матвей Солодовников

    02.04.2020 в 14:03

    Это Microsoft Docs теперь, но да, у них стало намного лучше чем было на TechNet и MSDN. И даже темную тему запилили по последней моде :)

    Точно, Docs. И темную тему, и версию на английском (но это не везде).

    В смысле нет пароля восстановления? Если политика настроена, он может храниться в AD DS, и следовательно администратор может передать его любым способом.

    Пароль есть, хранится в AD DS, но все равно после перезагрузки его нужно вводить самому.

    Ваша оценка: Thumb up Thumb down 0
    • Vadim Sterkin

      05.04.2020 в 10:56

      Матвей Солодовников: и версию на английском

      Гм… версия на английском исходная. Остальное — машинный перевод для всех новых доков. Какие-то переводятся людьми, но кмк это зависит от желаний и бюджета продуктовой группы. У Microsoft сейчас практически нет технических писателей, в Docs пишут ПГ — ПМы или разработчики.

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

      Ваша оценка: Thumb up Thumb down 0
  7. Виталий Кононов

    04.04.2020 в 13:40

    Вадим, спасибо! Четко, конкретно и по делу скопировал к себе для работы.
    Я бы еще рекомендовал в шапку «Мини-руководства» включить упоминание о ГОСТ 2.105-95 «ЕСКД. Общие требования к текстовым документам.» и ГОСТ 2.610-2006 «ЕСКД. Правила выполнения эксплуатационных документов.», а также на ГОСТ 7.31-2017 «СИБИД. Отчет о научно-исследовательской работе. Структура и правила оформления».
    Как показывает практика многие «технические писатели» с удивлением узнают о существовании стандартов на текстовые документы.

    Ваша оценка: Thumb up Thumb down 0
    • Vadim Sterkin

      05.04.2020 в 10:54

      Виталий, ГОСТы — это тоже руководства по стилям, конечно. Но в контексте этой статьи и целевой аудитории писателей и читателей они совершенно не нужны.

      Ваша оценка: Thumb up Thumb down 0
  8. Алексей Каманин

    13.04.2020 в 18:03

    Однозначно в закладки.
    Есть у меня рекомендации по оформлению презентаций. Так что этот пост в копилку.

    Ваша оценка: Thumb up Thumb down 0
  9. Alexiz Kadev

    14.04.2020 в 12:37

    1. Читал работать по 10-12 часов, вместо прежних 8-9.
    2. сложности возникают только с одним «чудесным» продуктом под названием Skype for business. То звук пропадает, то звонок на мобильный клиент не приходит или приходит, но с диким опозданием, то не все могут подключиться к конференции, то ещё что-нибудь. В том же WhatsApp таких проблем нет и близко. Мобильный клиент — вообще отдельная песня.
    3. эффективность оценить сложно. можно только сказать, что комфорт конечно повысился, а вот 10-12 часовой рабочий день радости не особо много доставляет.

    Ваша оценка: Thumb up Thumb down 0
    • Vadim Sterkin

      14.04.2020 в 15:24

      А с чем конкретно связано увеличение рабочего дня? Недостаток персонала?

      Ваша оценка: Thumb up Thumb down 0

Обсуждение завершено.

Subscribers

Популярные записи

  • MiniDumper — удобная утилита для анализа дампов при BSOD (21)
  • 8 возможностей проводника Windows, о которых вы могли и не знать (101)
  • Что общего у армянской сказки и эволюции флэш-памяти в SSD (74)
  • Windows 8.1 Update 1: что получается, когда Microsoft вас слушает (183)
  • [видео] Charu — самурайский менеджер буфера обмена (132)
  • Как грамотно уменьшить размер папки WinSxS в Windows 10, 8.1 и 8 (170)
  • Сколько у вас лишних разделов на диске? (204)
  • Еще →

Свежие комментарии

  • Vadim Sterkin к записи Как выполнять команды и скрипты от имени системы средствами Windows
  • Vadim Sterkin к записи Поддержите меня подпиской или донатом!
  • Валерий Плотников к записи Поддержите меня подпиской или донатом!
  • Артём Ракчеев к записи Нюансы управления звуком в Windows 10
  • Игорь к записи Поддержите меня подпиской или донатом!
  • Vadim Sterkin к записи Поддержите меня подпиской или донатом!
  • Игорь к записи Поддержите меня подпиской или донатом!
  • Vadim Sterkin к записи Поддержите меня подпиской или донатом!

Рекомендую ресурсы

  • Windows 10, etc — канал этого блога в Telegram
  • Инсайдеры Windows 10 — чат блога в Telegram
  • Community — новости предварительных сборок
  • Николай Павлов — тайны планеты Excel
  • Вадимс Поданс — PKI, PowerShell и Тера Патрик
  • Василий Гусев — PowerShell и другие скрипты
  • Kazun — PowerShell для взрослых

Реклама

Измененная тема eleven40 Pro на платформе Genesis · Архивы и метки · Правила (16+) · О рекламе · Обратная связь · Вход

Допускается копирование материалов без изменений, с указанием имени автора и гиперссылки на сайт.