Часть первая

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

Приятного чтения.

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

1) Документация востребована и ее читают.

2) Если ей не пользуются, то это происходит по следующим причинам:

"А где найти руководство"

  • На сайте программы отсутствует ссылка на файл справки

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

  • Документацию сложно найти

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

  • Отсутствует «справка» в меню

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

  • "F1 не работает!"

    Традиционно, контекстная справка в программах активируется нажатием клавиши F1. Поэтому пользователи в первую очередь будут нажимать эту клавишу и если она не будет работать, то скорее всего человек решит, что справки в вашей программе просто нет.

"Что-то не то с форматом"

  • Формат документа не поддерживается

    Данная ошибка часто встречалась у клиентов, которые разрабатывали межплатформенные программы. Создавая файл справки, разработчики часто забывали, что его могут открывать не только пользователи «винды» и интегрировали справку с продуктом только в формате CHM. Этот формат отлично поддерживается Windows и изначально умеет просматривать CHM файлы. Но для других операционок CHM не является "родным", и ваш клиент замучается открывать его например на MacOS или Ubuntu.

  • Формат документа не удобен для чтения на конкретном устройстве или в конкретной среде

    Казалось бы, универсальным решением универсальности документации являются HTML и CHM форматы. Имея доступ в интернет, пользовательскую документацию опубликованную на сайте можно открыть на любой платформе, а контекстно-зависимую справку просто нажав на кнопку F1.

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

    Решение простое – поставляйте ваш продукт вместе с документацией в формате PDF или разместите PDF файл на сайте, чтобы «мануал» можно было скачать на устройство. В таком случае у пользователя всегда будет под рукой локальная версия справки, к которой он сможет обратиться за помощью.

    "Навигационные проблемы"

  • Отсутствует поиск по документации

    Техническая документация к продукту сама по себе подразумевает большое количество разделов и даже с хорошей и логичной структурой пользователю будет тяжело найти в ней нужную информацию. Здесь поможет «поиск» по документу. Но ведь что в PDF, что в CHM формате функция поиска реализована по умолчанию. Тогда почему здесь эта ошибка?

    Потому что разработчики часто забывают, про онлайн документацию, которая является набором разных HTML файлов. В ней браузер может найти конкретные фразы только на странице, открытой в данный момент. Для поиска по всем разделам документации не забудьте создать особый скрипт или используйте Google Site Search.

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

Надеюсь, что она была полезна и интересна.

P.S. Под технической документацией в данной статье я имею в виду только руководство пользователя.

Комментарии (13)


  1. anonymous
    00.00.0000 00:00


  1. AndyPike
    04.03.2022 23:49
    +3

    Потому что ни кто не хочет тратить на это своё время.
    Всё написано юридическим языком, чтобы к ним нельзя было придраться.
    Это не интересная повесть, которую хочется читать, поэтому не стоит привлекать.
    Это только обязательства, которые на вас накладывают по закону.


    1. AndyPike
      04.03.2022 23:53
      +1

      За время написания отклика, статью изменили. Прошу не реагировать.


  1. kichrot
    05.03.2022 01:28
    +1

    Вопрос статьи поставлен несколько неверно, так как проблема не в пользователях, а в программах и программистах.

    Создатель программы должен исходить из простой мысли, что средний условный юзверь, это условный "умственно отсталый человек", который не читал и читать не умеет, и проектировать интерфейс и алгоритм взаимодействия программы с пользователем исходя из этого факта. Не знаю, какая практика и идеология сегодня, но ещё в начале 2000-х считалось правилом хорошего тона то, что минимум 50% кода описывало защиту от "дурака", т.е. от несанкционированных действий пользователя.

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

    Естественно идеал недостижим, но стремиться надо.


    1. ads83
      05.03.2022 05:40
      +1

      Создатель программы должен исходить из простой мысли, что средний условный юзверь, это условный "умственно отсталый человек", который не читал и читать не умеет, и проектировать интерфейс и алгоритм взаимодействия программы с пользователем исходя из этого факта. Не знаю, какая практика и идеология сегодня, но ещё в начале 2000-х считалось правилом хорошего тона то, что минимум 50% кода описывало защиту от "дурака", т.е. от несанкционированных действий пользователя

      Тут главное не переборщить, вовремя остановиться и помнить другое правило: создайте программу, которой может пользоваться любой дурак, и только дурак захочет ею пользоваться. :-)


      1. kichrot
        05.03.2022 07:56
        +1

        ... создайте программу, которой может пользоваться любой дурак, и только дурак захочет ею пользоваться.

        Вы правы. Но, это опять же проблема программиста, а не пользователя: Если программист дурак, то и программа у него дурацкая. :)


        1. fotobred
          06.03.2022 21:51

          Когда-то давно у меня в руках оказалось официальное руководство по ЕМНИП "Виндовс сервер" на русском языке. Это было что-то типа такого:

          Для входа в панель изменения настроек режима отображения панели инструментов выберите пунт меню "Панель изменения настроек режима отображения панели инструментов"

          И такое творчество встречается и сейчас...


  1. MinimumLaw
    05.03.2022 07:43
    +1

    Основная проблема - это разный уровень подготовки пользователей. Ну, и личностные характеристики, конечно. Каждый конечный пользователь всегда переоценивает свои знания и пропускает разделы "быстрое знакомство" или "учебник". А дальше... Про F1 помнят уже только динозавры. Этот пункт можно вычеркивать. Разница между меню "справка" и бумажной документацией из моего опыта не принципиальна. А вот содержимое... Но тут все очень специфично для продукта, и выдавать готовые рецепты было бы дурным тоном. А вот выкладывание видеоуроков (коротких) с решением типовых задач и внятными комментариями по "углублению"... Да, "динозавров" это выбешивает. Быстрее прочитать. Но это отлично работает с современной аудиторей.

    Отдельно стоит сказать о тех случаях, когда формат, стиль и содержание документации четко регламентировано. В некоторых случаях можно попробовать пересмотреть регламент, но чаще разумным вариантом будет выпуск документа типа "Руководство по быстрому старту". Было бы неплохо, чтоб оно шло приложением к обязательной документации и не занимало больше двух страниц.

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


    1. kichrot
      05.03.2022 08:06
      +1

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

      В идеале "Руководство пользователя" должно быть частью ТЗ выданного заказчиком программисту.

      Но, в свою очередь, встретить грамотное ТЗ, такая же проблема, как встретить грамотное "Руководство пользователя".


  1. jedi0798
    05.03.2022 09:06

    Часто, их пишут профессионалы, для профессионалов. Потому и не читается. А если и читается, то не понимается)


  1. DarkWolf13
    05.03.2022 11:14
    +1

    Проблема в том что грамотное и полное ТЗ окончательно может сформироваться уже при 90%% готовности проекта, т.к. много доп согласований и изначально не закладываемых работ и решений, т.к. изначально тз может звучать в стиле "семь красных линий", а после начала работы с заказчиком проект может стать вполне реализуемым, но не отвечать изначальному ТЗ

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

    1. не хотят (решается в стиле если ничего не помогает прочтите наконец инструкцию, т.е в стиле пром предприятий расписывается за инструктаж, т.е расписываемся по прочтению, )

    2. инструкция слишком короткая, без пояснений сложных моментов.

    3. инструкция слишком сложная и ее не возможно воспринимать пользователям к их непосредственным действиям , т.е в какой момент какую последовательность применять.

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

    5. Инструкции есть все но некоторые части слегка устарели после обновлении версии проекта.

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


  1. Grigorenkovic
    05.03.2022 13:49

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


  1. Urub
    06.03.2022 19:27

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