Часть первая
Данная статья не предполагает каких-то заумных и крайне неочевидных советов по написанию и проверке технической документации. Многие из перечисленных «советов» многим покажутся очевидными, но из раза в раз, анализируя документацию наших пользователей, мы сталкиваемся с одними и теми же банальными ошибками, которые чаще всего происходят из-за фактора «забыл». Так что данный пост можно расценить как памятку не техническому писателю.
Приятного чтения.
За долгое время работы над программой для написания этих самых «хелпов», наша команда рассмотрела и проанализировала множество сторонних проектов, руководители которых обращались к нам за помощью. Чаще всего с их стороны были вопросы о реализации тех или иных приемов в пользовательской документации к их продуктам. И на основе такого опыта мы сделали два вывода:
1) Документация востребована и ее читают.
2) Если ей не пользуются, то это происходит по следующим причинам:
"А где найти руководство"
-
На сайте программы отсутствует ссылка на файл справки
Всем уже давно известно, что хорошо бы выложить руководство пользователя на сайт, но иногда кто-то потом просто забывает создать отдельную кнопку в меню со ссылкой на документацию. Решение этой проблемы очевидно: добавьте документацию в меню сайта, чтобы никто не мучился и не искал ваш «хэлп».
-
Документацию сложно найти
Да, ошибка похожа на предыдущую, но отличается тем, что разработчик не забыл указать ссылку на документацию, а решил, что пользователь сам спокойно сможет ее отыскать где-то на задворках сайта. Это не так. Пользователь ленив, помните это. Просто добавьте на видное место ссылку на документацию.
-
Отсутствует «справка» в меню
Решение простое: пробегитесь глазами по интерфейсу программы и попробуйте найти место для элементов управления, которые будут открывать файл-помощник.
-
"F1 не работает!"
Традиционно, контекстная справка в программах активируется нажатием клавиши F1. Поэтому пользователи в первую очередь будут нажимать эту клавишу и если она не будет работать, то скорее всего человек решит, что справки в вашей программе просто нет.
"Что-то не то с форматом"
-
Формат документа не поддерживается
Данная ошибка часто встречалась у клиентов, которые разрабатывали межплатформенные программы. Создавая файл справки, разработчики часто забывали, что его могут открывать не только пользователи «винды» и интегрировали справку с продуктом только в формате CHM. Этот формат отлично поддерживается Windows и изначально умеет просматривать CHM файлы. Но для других операционок CHM не является "родным", и ваш клиент замучается открывать его например на MacOS или Ubuntu.
-
Формат документа не удобен для чтения на конкретном устройстве или в конкретной среде
Казалось бы, универсальным решением универсальности документации являются HTML и CHM форматы. Имея доступ в интернет, пользовательскую документацию опубликованную на сайте можно открыть на любой платформе, а контекстно-зависимую справку просто нажав на кнопку F1.
Однако стоит помнить, что интернет, по разным причинам, в наше время доступен не всем и не всегда, и пользователь может прибегнуть к документации, не находясь в программе.
Решение простое – поставляйте ваш продукт вместе с документацией в формате PDF или разместите PDF файл на сайте, чтобы «мануал» можно было скачать на устройство. В таком случае у пользователя всегда будет под рукой локальная версия справки, к которой он сможет обратиться за помощью.
"Навигационные проблемы"
-
Отсутствует поиск по документации
Техническая документация к продукту сама по себе подразумевает большое количество разделов и даже с хорошей и логичной структурой пользователю будет тяжело найти в ней нужную информацию. Здесь поможет «поиск» по документу. Но ведь что в PDF, что в CHM формате функция поиска реализована по умолчанию. Тогда почему здесь эта ошибка?
Потому что разработчики часто забывают, про онлайн документацию, которая является набором разных HTML файлов. В ней браузер может найти конкретные фразы только на странице, открытой в данный момент. Для поиска по всем разделам документации не забудьте создать особый скрипт или используйте Google Site Search.
На этом я бы хотел закончить первую часть данной статьи.
Надеюсь, что она была полезна и интересна.
P.S. Под технической документацией в данной статье я имею в виду только руководство пользователя.
Комментарии (13)
AndyPike
04.03.2022 23:49+3Потому что ни кто не хочет тратить на это своё время.
Всё написано юридическим языком, чтобы к ним нельзя было придраться.
Это не интересная повесть, которую хочется читать, поэтому не стоит привлекать.
Это только обязательства, которые на вас накладывают по закону.
kichrot
05.03.2022 01:28+1Вопрос статьи поставлен несколько неверно, так как проблема не в пользователях, а в программах и программистах.
Создатель программы должен исходить из простой мысли, что средний условный юзверь, это условный "умственно отсталый человек", который не читал и читать не умеет, и проектировать интерфейс и алгоритм взаимодействия программы с пользователем исходя из этого факта. Не знаю, какая практика и идеология сегодня, но ещё в начале 2000-х считалось правилом хорошего тона то, что минимум 50% кода описывало защиту от "дурака", т.е. от несанкционированных действий пользователя.
Идеальная программа вообще не должна требовать чтения документации пользователем, для нормальной работы с ней.
Естественно идеал недостижим, но стремиться надо.
ads83
05.03.2022 05:40+1Создатель программы должен исходить из простой мысли, что средний условный юзверь, это условный "умственно отсталый человек", который не читал и читать не умеет, и проектировать интерфейс и алгоритм взаимодействия программы с пользователем исходя из этого факта. Не знаю, какая практика и идеология сегодня, но ещё в начале 2000-х считалось правилом хорошего тона то, что минимум 50% кода описывало защиту от "дурака", т.е. от несанкционированных действий пользователя
Тут главное не переборщить, вовремя остановиться и помнить другое правило: создайте программу, которой может пользоваться любой дурак, и только дурак захочет ею пользоваться. :-)
kichrot
05.03.2022 07:56+1... создайте программу, которой может пользоваться любой дурак, и только дурак захочет ею пользоваться.
Вы правы. Но, это опять же проблема программиста, а не пользователя: Если программист дурак, то и программа у него дурацкая. :)
fotobred
06.03.2022 21:51Когда-то давно у меня в руках оказалось официальное руководство по ЕМНИП "Виндовс сервер" на русском языке. Это было что-то типа такого:
Для входа в панель изменения настроек режима отображения панели инструментов выберите пунт меню "Панель изменения настроек режима отображения панели инструментов"
И такое творчество встречается и сейчас...
MinimumLaw
05.03.2022 07:43+1Основная проблема - это разный уровень подготовки пользователей. Ну, и личностные характеристики, конечно. Каждый конечный пользователь всегда переоценивает свои знания и пропускает разделы "быстрое знакомство" или "учебник". А дальше... Про F1 помнят уже только динозавры. Этот пункт можно вычеркивать. Разница между меню "справка" и бумажной документацией из моего опыта не принципиальна. А вот содержимое... Но тут все очень специфично для продукта, и выдавать готовые рецепты было бы дурным тоном. А вот выкладывание видеоуроков (коротких) с решением типовых задач и внятными комментариями по "углублению"... Да, "динозавров" это выбешивает. Быстрее прочитать. Но это отлично работает с современной аудиторей.
Отдельно стоит сказать о тех случаях, когда формат, стиль и содержание документации четко регламентировано. В некоторых случаях можно попробовать пересмотреть регламент, но чаще разумным вариантом будет выпуск документа типа "Руководство по быстрому старту". Было бы неплохо, чтоб оно шло приложением к обязательной документации и не занимало больше двух страниц.
Вообще по документации это очень больная тема. Что касается пользовательской документации, то в идеале ее должны писать не разработчики. Но то в идеале. А в реальной жизни единственный совет, который можно и должно дать разработчику - в документации должен быть четко обозначенный пункт, открыв который типовые действия смог бы выполнить школьник из начальной школы. Идеально уложиться в две страницы - т.е. быть шпаргалкой, в которую всегда можно заглянуть не занимаясь поиском по многостраничному талмуду. И именно эту шпаргалку надо корректировать основываясь на обратной связи.
kichrot
05.03.2022 08:06+1.... Что касается пользовательской документации, то в идеале ее должны писать не разработчики. ...
В идеале "Руководство пользователя" должно быть частью ТЗ выданного заказчиком программисту.
Но, в свою очередь, встретить грамотное ТЗ, такая же проблема, как встретить грамотное "Руководство пользователя".
jedi0798
05.03.2022 09:06Часто, их пишут профессионалы, для профессионалов. Потому и не читается. А если и читается, то не понимается)
DarkWolf13
05.03.2022 11:14+1Проблема в том что грамотное и полное ТЗ окончательно может сформироваться уже при 90%% готовности проекта, т.к. много доп согласований и изначально не закладываемых работ и решений, т.к. изначально тз может звучать в стиле "семь красных линий", а после начала работы с заказчиком проект может стать вполне реализуемым, но не отвечать изначальному ТЗ
По личному опыту разработки и использования различных продуктов большинство "ситуаций" вызвано неверными действиями пользователей, не читавших документацию. А вот дальше вопрос почему не читают:
не хотят (решается в стиле если ничего не помогает прочтите наконец инструкцию, т.е в стиле пром предприятий расписывается за инструктаж, т.е расписываемся по прочтению, )
инструкция слишком короткая, без пояснений сложных моментов.
инструкция слишком сложная и ее не возможно воспринимать пользователям к их непосредственным действиям , т.е в какой момент какую последовательность применять.
есть несколько инструкций общая и отдельные составляющие проекта, но непонятна связанность для конкретных действий конечного пользователя при работе с проектом
-
Инструкции есть все но некоторые части слегка устарели после обновлении версии проекта.
на основании все выше перечисленного ну и немного подсмотрел пришел к выводу что оптимальным это написание краткой инструкции в стиле "быстрого старта", но ссылками на инструкции составляющих частей, и расширенную инструкцию с подробным описанием моментов работы в проектом.
Grigorenkovic
05.03.2022 13:49Исходя из собственного опыта и процессов создания и демонстрации инструкций, скажу что в разных компаниях по-разному. Мало того, для каждого индивидуальный подход нужен. Особенно для топ-менеджмента. Одни очень довольны строгими инструкциями и за каждое лишнее слово спросят, другие очень не хотят инструкций в тестовом формате, только демонстрация или видеоинструкции, третьи пытаются сами и спрашивают только то что не поняли и довольны таким подходом...
Urub
06.03.2022 19:27Хорошим решением был бы способ "автоматической" написания документации во время написания/правки кода, иначе на нее у программиста не остается времени никогда т.к. всегда есть код который надо написать/исправить.
anonymous