В случае возникновения критической ошибки обновления:
1. Установите причину ошибки.
2. Устраните причину ошибки.

Документация Microsoft

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

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

Древнее и сакраментальное RTFM преследует нас повсюду. Волей-неволей мы вынуждены постоянно читать инструкции: к технике, приборам, приложениям, системам.

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

Сколько раз я натыкался на поля с совершенно неочевидными названиями — и не сосчитаешь. Изредка попадались поля вообще без названий (а чего там что-то ещё писать, всё же и так понятно!) В общем, без инструкций пока никак не обойтись.

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

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

1. Объясняем назначение каждого элемента

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

Тут важно оперировать не языком интерфейса, а языком бизнес-процессов и предметной области пользователя. Вы не поверите, как часто эти языки не совпадают. В общем, нужно добросовестно поработать переводчиком.

Ещё нужно внимательно посмотреть на другие соседние элементы и проверить, нет ли среди них похожих по названию или содержанию. Если в окне есть семейка полей «Валюта 1», «Валюта 2», «Валюта по умолчанию», «Валюта главного контрагента» и т.д., то нужно обстоятельно и со всеми подробностями расписать, чем же эти валюты различаются.

2. Перечисляем все ограничения значений

Если поле подразумевает ввод каких-то значений, то нужно обязательно рассказать, каким это значение может быть:

• Формат. Например, как разделяется целая и дробная часть: запятой или точкой.

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

• Диапазон. Какое у поля наибольшее и наименьшее допустимое значение. Бывает, что формально в интерфейсе ограничение не задано, но ведь значение поля нужно куда-то сохранить. А это «куда-то» имеет свой тип. А тип имеет допустимый диапазон значений.

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

• Единицы измерения. Вот в том же окне с кучей валют хаотично разбросано несколько полей с названием «Сумма». И в какой же валюте нужно вводить каждую из этих сумм? Как говорится, тут могут быть варианты.

• Значение по умолчанию. Что будет, если пользователь не задаст значение поля. Оно останется пустым? Или заполнится каким-то значением? А это значение будет показано пользователю или он узнает о нём де-факто, уже после сохранения записи?

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

Удивительное поле «Приоритет»

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

• чем больше значение поля, тем выше приоритет;

• чем больше значение поля, тем ниже приоритет;

• приоритет можно задать только положительный;

• внезапно можно выбрать не только положительный, но и отрицательный приоритет (что бы это ни значило);

• нулевой приоритет задавать нельзя;

• нулевой приоритет задавать нельзя, но по умолчанию значение поля — ноль;

• нулевой приоритет задавать можно;

• чем больше значение, тем выше приоритет, но внезапно значение '0' — это самый высокий приоритет из всех;

• предыдущий вариант, но вместо '0' — значение '-1';

• если задать приоритет, который уже задан у другой записи, то ничего не случится;

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

• приоритет не может быть пустым;

• приоритет может быть пустым — такие записи наименее приоритетны;

• приоритет может быть пустым — такие записи наиболее приоритетны;

• приоритет может быть пустым — такие записи вообще не рассматриваются...

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

3. Описываем правила доступности редактирования

Случалось ли вам вдруг обнаруживать в привычном окне, что нужное вам поле недоступно для редактирования? Ну, в смысле, что оно disable.

А всегда ли вы знаете, почему именно оно недоступно? Я вот таким знанием похвастаться не могу. Бесчисленное количество раз я обнаруживал, что не могу задать или отредактировать то, что мне очень надо задать или отредактировать.

Причин тут может быть множество: у вас нет нужной роли, запись находится в определённом статусе, в каком-то другом поле выбрано какое-то определённое значение... Кстати, это поле может находиться вообще в другом окне.

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

4. Раскрываем все связи и закономерности

Часто бывает, что поля в окне связаны друг с другом: включаешь один переключатель — отключаются другие. Или наоборот. Кстати, эти связи не всегда транзитивны. Или выбор значения в одном поле обнуляет значение в другом. Причём обнуляет с концами, без возможности восстановления того, что там было.

В некоторых интерфейсах логику всех этих взаимосвязей проследить очень трудно. Это чем-то похоже на головоломку: пройди квест, найди все связи, установи нужное значение всех полей — и получишь приз. Ну, например, успешно сохранишь карточку клиента.

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

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

5. Документируем условия доступности значений

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

Вот он справочник — открыт в соседнем окне. Вот в этом справочнике запись с каким-то нужным значением. У неё даже статус стоит «Действует». И дата окончания действия не задана. Но всё равно в нужном поле эту запись не выбрать — хоть ты тресни. И что делать — непонятно. Гадать можно сколько угодно.

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

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

Часто документация просто тупо пересказывает интерфейс, не давая никаких новых знаний о логике работы программы. В договоре указано, что программа поставляется с пакетом документации — вот он, пожалуйста, чего вы ещё хотите?

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

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