Как описать графический интерфейс пользователя?

Приемы описания графического интерфейса пользователя. Впервые опубликована 09.03.2005 года под названием «Графический интерфейс пользователя». За весь срок своего существования статья уверенно удерживает 2 место в рейтинге просмотров, уступая лишь циклу статей к.т.н. В. А. Глаголева о стоимости разработки техдокументации. Редакция от 10.05.2021.

Создан 05.03.2005 10:47:42

- Кривой графический интерфейс пользователя

Графический интерфейс пользователя по определению должен быть кривым 🤪

Смотрите:
Исходные данные
Группы пользователей и уровень подготовки пользователей
Лирическое отступление
Схема «действие - результат» в совокупности с подходом «делай, как я сказал»
Связка «общие сведения, назначение и состав»
Реализация практических приемов описания графического интерфейса пользователя
Что получилось в результате
Заключение

Исходные данные

Из раздела форума:

- Как писать руководство пользователя отзыв

Речь шла о графическом интерфейсе пользователя, о приемах его описания в руководствах пользователей программ. Руководство пользователя, как таковое, имеет место быть только в ГОСТ 34.ххх, а в ГОСТ 19.ххх есть руководство оператора, руководство программиста и руководство системного программиста, которые, в совокупности, и являются руководством пользователя, см. «Как писать руководство пользователя? Часть I» и «Как писать руководство пользователя? Часть II».

Итак, что мы имеем? Имеем:

  • реальное деление пользователей на группы, различающиеся уровнем подготовки;
  • схему «действие - результат» в совокупности с подходом «делай, как я сказал»;
  • испытанную связку «общие сведения, назначение и состав», см. «Как писать техническое задание?!»;
  • и, как всегда, рекомендации ГОСТ 19.ххх и IEEE Std 1063-2001.

Группы пользователей и уровень подготовки пользователей

Куда вы руки лезете свои?!

«Армейские приколы»

Надо отдать должное телевизионной рекламе. Если отбросить перлы про активный кислород и гигиеническую чистоту туалета, можно заметить, что реклама (по-своему) четко классифицирует материальный мир. Реклама убеждает нас, что существуют, к примеру, Tide и обычный стиральный порошок, Fairy и обычное моющее средство. И так далее.

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

Рекламный прототип

«Мелкомягкий» аналог

Мозг

группа Administrators

отсутствует

группа Power (Advanced) users

Желудок

группа Users

Немного о реалиях по каждой группе пользователей программы (вне рамок прав и полномочий).

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

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

(Печальный факт стремительного сокращения числа Administrators и роста числа Users налицо).

Отечественный подход привычно черно-белый: «кто не с нами - тот против нас», «либо пан, либо пропал», «либо папаха, либо плаха» - третьего не дано. Реально «оттенки серого» имеют место. Речь о Power (Advanced) users - промежуточном состоянии между мозгом и желудком.

Энергичные (дословный перевод - прелесть!) продвинутые пользователи, в отличие от ленивых и нелюбопытных Users, утратили страх перед неизведанным. В силу своей неиссякаемой энергии, продвинутые пользователи действуют методом «научного тыка», вечно суют нос и руки, куда не следует. Administrators (системные) ненавидят продвинутых пользователей лютой ненавистью - «куда вы руки лезете свои?!».

Таким образом, жизненные реалии ставят автора любого руководства пользователя перед выбором:

  1. либо разрабатывать варианты руководства для каждой группы пользователей (так, к примеру, предусмотрено ГОСТ 19.503-79, ГОСТ 19.504-79 и ГОСТ 19.505-79);
  2. либо разработать единое «компромиссное» руководство, способное:
    • быстро сформировать рефлексы у пользователя с мозгом «облегченного полевого образца», заставляющие такого пользователя неосознанно, но безошибочно выполнять задачу;
    • не вызвать раздражения пользователя-профессионала излишней детализацией каждого шага - как нажимать кнопку Cancel, как вводить текст, выбирать значения из списков и т. д.

Второй вариант, очевидно, можно считать приемлемым. Именно поэтому не стоит сорить в рунете страничками вроде «Как сделать хорошее руководство пользователя», а следует детально и без спешки проработать обобщенную структуру руководства пользователя (см. «Как писать руководство пользователя? Часть I» и «Как писать руководство пользователя? Часть II»).

Лирическое отступление

Некоторые т.н. «технические писатели» руководствуются в своей жизнедеятельности исключительно т.н. «законами восприятия». Законы восприятия объективно существуют, как и законы физики, - факт бесспорный.

Не новость, что существует условное деление всего рода человеческого по виду восприятия информации (и ряду иных признаков) на дигиталов, аудиалов, визуалов и кинестетиков.

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

Аудиалов единицы. Людей, способных воспринимать все со слов, единицы процентов, если судить по вузовской аудитории. На лекциях всегда присутствует 2-3 «бездельника» (курс - 250 человек), не утруждающие себя конспектированием. В течение двух академических часов товарищи активно «ловят ворон», разгильдяйским видом своим раздражая преподов, а затем блестяще сдают сессию.

Визуалов побольше. Такой публике предпочтительно подавать материал в виде блок-схем алгоритмов, нежели чем в виде хорошо структурированного текста.

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

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

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

  • дигиталов - 25 %;
  • аудиалов - 5 %;
  • визуалов - 35 %;
  • кинестетиков - 35 %.

У наших заокеанских «партнеров» ситуация впятеро хуже:

  • дигиталов - 5 %;
  • аудиалов - 5 %;
  • визуалов - 45 %;
  • кинестетиков - 45 %,

что не мешает им жить впятеро лучше нас, занимаясь разбоем и грабежом в мировом масштабе...

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

Схема «действие - результат» в совокупности с подходом «делай, как я сказал»

Было бы величайшей ошибкой думать...

В.И. Ленин, ПСС, т. 41, с. 55

Схема описания графического интерфейса пользователя «действие (пользователя) - результат (ответ программы)» изначально заложена как в ГОСТ 19.ххх, так и в IEEE Std 1063-2001.

В ГОСТ 19.ххх указанная схема представлена структурой смежных разделов:

  • описание выполняемой (выполнения) функции;
  • ответы программы на команды для выполнения функции.

В IEEE Std 1063-2001 имеется ключевая фраза «Documentation shall explain the formats and procedures for user-entered software commands, including... Examples should illustrate the use of commands».

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

И снова из манифеста: «В то же время не следует думать, что...». Честное слово, если бы автор настоящей статьи отыскал манифест г-на Кагарлицкого где-нибудь далеко в сети, а не на известном «философтовском» сайте (и без указания авторства), решение было бы однозначным: автор манифеста (ни много ни мало) доктор наук генерал-полковник Д. А. Драгунский, в прошлом - один из блистательнейших авторов «Литературной газеты». Человек не может и не должен думать! Человек способен лишь расставлять приоритеты (что лучше - попИсать или пописАть, передохнУть или передОхнуть - выбрать подходящие варианты. Это та самая омофония?), человеку может что-то «прийти в голову» - но не более того. Рефлексы, рефлексы и тысячу раз рефлексы.

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

Users и Power (Advanced) users следует «вести через перевал» согласно подходу «делай, как я сказал» по жесткой схеме «действие - результат».

Для выполнения операции ТАКОЙ-ТО (или «указанной операции» - помним о шаблонном построении фраз, формализации и унификации) следует («следует» - вежливая отстраненность: хочешь получить результат - делай, как я сказал, не хочешь - не мои проблемы):

  1. взять (действие в повелительном наклонении) отвертку в правую руку (рисунок, поясняющий результат);
  2. вставить отвертку куда-нибудь (рисунок, поясняющий результат);
  3. повернуть отвертку на 90 град. по часовой стрелке (рисунок, поясняющий результат);
  4. и так далее.

И все получится, бездумно и без напряжения. И все будут счастливы.

Не следует детально расписывать, как «согнуть пальцы», чтобы удержать отвертку. Хватательный рефлекс в равной степени развит и у Users, и у Power (Advanced) users с пеленок. (Неспроста же дети мгновенно осваивают действия с графическим интерфейсом пользователя). Сведения о выполнении операций вида drag-and-drop и им подобных читатель сможет самостоятельно почерпнуть из руководства пользователя операционной системы.

Administrators, которым подобная детализация ни к чему, вопреки цели руководства будут испытывать «ощущение авторитетности изложения» по-Кагарлицкому.

Связка «общие сведения, назначение и состав»

Связка «общие сведения, назначение и состав» многим известна по статье Как писать техническое задание?! Связка, как было показано, не противоречит ни манифесту, ни IEEE Std 1063-2001, ни (упаси боже!) ГОСТ 19.ххх. Переходим к решению поставленной задачи.

Реализация практических приемов описания графического интерфейса пользователя

Многие пользователи AuthorIT отмечают, что AuthorIT User Guide «малость туповат». Что неудивительно - в Новой Зеландии, на «родине» AuthorIT, о российских подходах «мужики-то и не знают». К рассмотрению предлагается альтернативный вариант описания графического интерфейса пользователя в рамках одной из возможностей AuthorIT (фрагмент руководства с подробными комментариями).

Читателю, причисляющему себя к разработчикам-профессионалам, рекомендуется перейти непосредственно к разделу Что получилось в результате.

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

В двух словах: AuthorIT Administrator позволяет создавать, а AuthorIT позволяет вставлять в свои топики переменные нескольких видов в формате <ИМЯ_ПЕРЕМЕННОЙ>. При публикации в документ MSWord (или в документ иного формата) переменные топиков замещаются соответствующими им значениями. Например, созданная в AuthorIT Administrator переменная <PROG_NAME> со списком значений {FineDeveloper; AuthorIT; MSWord и т.д.}, вставленная в топик AuthorIT, в зависимости от пожелания разработчика документа, будет «выглядеть» так:

В тексте топика

В тексте публикации

<PROG_NAME> обеспечивает выполнение...

либо

FineDeveloper обеспечивает выполнение...

либо

AuthorIT обеспечивает выполнение...

либо

MSWord обеспечивает выполнение...

Для Administrators информации более чем достаточно. С графическим интерфейсом пользователя Administrators легко справятся. Users же замучают Administrators вопросами «что и где жать».

Смотрите:
Переменные в AuthorIT
Переменные AuthorIT (общие сведения)
Переменные в AuthorIT (назначение)
Переменные в AuthorIT (состав)
Использование переменных в AuthorIT (разъяснения)
Действия с переменными AuthorIT (разъяснение)

Переменные в AuthorIT

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

Переменные AuthorIT (общие сведения)

Что общего можно сказать о переменных? Очевидно, что все переменные характеризуются, как минимум:

  • назначением;
  • областью применения;
  • структурой описания;
  • способами манипуляции:
    • переменными в целом;
    • свойствами переменных.
  • синтаксисом;
  • результатом применения.

Пояснение сказанного словами: любая переменная для чего-то предназначена, где-то может быть использована и так далее.

О назначении:

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

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

Об области применения:

Переменные могут быть вставлены в тексты топиков AuthorIT для замещения кратким <ИМЯ_ПЕРЕМЕННОЙ> многократно повторно используемых:

  • фрагментов текста;
  • элементов графики;
  • файловых объектов;

параметров системы (дата, время, имя пользователя и пр.).При некотором умственном напряжении Users поймут, что фрагмент - это кусочек текста, элемент графики - картинка, а файловый объект - просто файл.

О структуре описания переменных:

Описания переменных представлены полями:

  • variable - полем имени переменной (в текстовом формате);
  • default (value) - полем значения по-умолчанию (полем значения);
  • description - полем описания (в текстовом формате);
  • type - полем типа переменной (возможные значения - Text, List Of Values, File Objects, System);
  • style - полем стиля. Возможные значения сведены в Таблицу.

don't inherit

none

Buttons a

Emphasis a

Expanding Inline a

Menu Options a

Monospace a

Special Bold a

Subscript a

Superscript a

Symbols a

Winding Symbols a

Вот это сложнее. Но неважно. Станет понятно позже, по мере детализации.

О возможностях манипуляции переменными:

AuthorIT Administrator обеспечивает возможность создания (добавления), копирования, удаления, назначения и редактирования (изменение полей описания) переменных (за исключением переменных System).

О возможности манипуляции свойствами переменных:

AuthorIT Administrator обеспечивает возможность изменения значений полей описания переменных (за исключением переменных System).

О синтаксисе в духе метаязыка:

Имена переменных заключаются в угловые скобки, например <PROGRAM_NAME>.

О результате применения:

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

Переменные в AuthorIT (назначение)

О назначении переменных было сказано выше, но в самом общем плане (умышленно). Здесь более детально о назначении переменных.

Переменные AuthorIT предназначены:

  • для хранения фрагментов текста, элементов графики, файловых объектов и системных переменных - многократно повторно используемых элементов информационного наполнения документов;
  • для замещения перечисленных выше элементов информационного наполнения короткими именами переменных в топиках AuthorIT;
  • для замещения имен переменных элементами информационного наполнения в публикуемых документах;

для публикации различных элементов информационного наполнения в различных версиях типовых документов. Назначение проясняется. Ход «мыслей» Users: «переменной <FRAGMENT_TEKSTA> можно присвоить значение, к примеру, «в чаще леса жил-был цитрус, да но фальшивый экземпляр», повтыкать указанную переменную в разные топики AuthorIT, а когда документ будет опубликован, в тексте документа, вместо переменной <FRAGMENT_TEKSTA>, будут вставлены строчки «в чаще леса жил-был цитрус, но фальшивый экземпляр»».

Предыдущий абзац - отличный объект для «критики» со стороны т.н. «маститых технических писателей». Пускай «покритикуют» ход «мыслей» Users.

Переменные в AuthorIT (состав)

Что можно сказать о составе переменных? Переменные могут быть классифицированы по виду (по полю тип). Классификация - это ведь тоже состав.

Слово тип вызывает негативные ассоциации - «вертится тут мрачный тип, скользкий тип, подозрительный тип». А позитивный синоним вид не «звучит». Далее просто - переменная type.

В состав переменных AuthorIT входят переменные четырех видов:

  • Text;
  • List Of Values;
  • File Objects;
  • System.

Состав переменных приведен, теперь подробно об общих сведениях, назначении и составе каждой переменной.

Смотрите:
Переменные Text (разъяснения)
Переменные List Of Values (разъяснения)
Переменные File Objects и System

Переменные Text (разъяснения)

Общие сведения:

Значение переменной Text представляет собой строку, состоящую из набора символов (a-z, A-Z, _). Переменная Text может хранить (иметь) единственное значение.

Назначение (конкретно):

Переменные Text предназначены:

  • для хранения фрагментов текста в виде значений переменных;
  • для замещения фрагментов текста короткими именами переменных в топиках AuthorIT;
  • для замещения имен переменных фрагментами текста в публикуемых документах;
  • для публикации различных фрагментов текста в различных версиях типовых документов.

Состав:

Строка значения переменной Text может включать в себя от 0 до 2000 символов.

Ход «мыслей» Users: «Ага, значит в переменную Text <FRAGMENT_TEKSTA> можно вколотить до 2000 знаков».

Переменные List Of Values (разъяснения)

Общие сведения:

Значения переменных List Of Values представляют собой набор (список) строк, состоящих из набора символов (a-z, A-Z, _).

В отличие от переменных Text, переменные List Of Values могут хранить несколько значений (список значений). Текущим значением переменной может быть любой элемент из списка значений, выбранный пользователем с помощью AuthorIT Administrator.

Назначение:

Переменные List Of Values предназначены:

  • для хранения фрагментов текста в виде значений переменных;
  • для замещения фрагментов текста короткими именами переменных в топиках AuthorIT;
  • для замещения имен переменных фрагментами текста в публикуемых документах;
  • для публикации различных фрагментов текста в различных версиях типовых документов.

Состав:

Строки значений переменных List Of Values могут включать в себя от 0 до 255 символов.

Ход «мыслей» Users: «Ага, значит переменная List Of Values может иметь несколько значений, а отображаться в тексте документа будет только то, которое назначишь текущим».

Переменные File Objects и System

Переменные File Objects и System рассматриваться в статье не будут (лень). Отметим только, что AuthorIT предоставляет ряд переменных System по-умолчанию.

- Список переменных по-умолчанию

Использование переменных в AuthorIT (разъяснения)

Использование переменных сводится к вставке имени переменной в текст топика AuthorIT. Для вставки переменной в текст топика AuthorIT следует:

  • запустить программу AuthorIT;
  • открыть требуемый топик;
  • выбрать требуемую позицию в тексте топика для вставки переменной;
  • выбрать пункт Insert главного меню AuthorIT;
  • в выпадающем меню указать пункт Variables;
  • в подчиненном меню выбрать требуемую переменную из списка.
  • В результате вставки в требуемой позиции текста топика будет отображена переменная в формате <ИМЯ_ПЕРЕМЕННОЙ>, например, 10 Май 2021 г. при вставке переменной System Long Date.

Действия с переменными AuthorIT (разъяснение)

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

Смотрите:
Создание (добавление) новой переменной (разъяснение)
Выводы по разделу
Копирование переменной (разъяснения)
Удаление переменной (разъяснение)

Создание (добавление) новой переменной (разъяснение)

Ни в коем случае не следует детально расписывать стандартные действия по работе с графическим пользовательским интерфейсом. Не следует разъяснять пользователю назначение кнопки Cancel и иных типовых элементов графического пользовательского интерфейса. Для указанных целей имеются руководства от гг. Торвальдса и Гейтса.

Для создания (добавления) новой переменной (выполнения указанной операции) следует:

  1. Запустить AuthorIT Administrator стандартными средствами операционной системы. В случае успешного запуска на рабочем столе будет отображено окно со списком наиболее часто используемых библиотек;

    - Запуск AuthorIT Administrator
  2. Выбрать из списка требуемую библиотеку;
  3. Нажать кнопку OK. На рабочем столе будет отображено окно Enter Library Password;

    - Окно Enter Library Password
  4. После выбора из выпадающего списка User name имени пользователя и ввода пароля в текстовое поле Password нажать кнопку Login. На рабочем столе будет отображено главное окно программы AuthorIT Administrator;

    - Главное окно AuthorIT Administrator
  5. Выбрать пункт Variables главного меню;
  6. В выпадающем меню выбрать пункт Maintain Variables. На рабочем столе будет отображено окно Variables;

    - Окно Variables
  7. Нажатием правой кнопки мыши в поле вызвать (открыть) всплывающее меню и выбрать пункт Add или нажать кнопку Add. На рабочем столе будет отображено окно Variable <> default settings;

    - Окно Variable default settings
  8. Ввести в поле Name (внутри угловых скобок) имя переменной (например, proba);
  9. Выбрать из выпадающего списка Type требуемый тип переменной (например, Text);
  10. Выбрать из выпадающего списка Style требуемый стиль (например, оставить по умолчанию);
  11. Ввести в поле Value текст значения переменной (например, проба пера);
  12. Ввести в поле Description текст описания переменной (например, Пробная переменная);
  13. Нажать кнопку Apply. Окно примет вид, изображенный на рисунке (ниже);

    - Окно Variable proba default settings
  14. Нажать кнопку OK. На рабочем столе будет отображено окно Variables, содержащее в первой позиции списка переменных вновь созданную переменную proba;

    - Окно Variables с переменной proba
  15. Нажать кнопку OK;
  16. Закрыть AuthorIT Administrator стандартными средствами операционной системы (при необходимости).

Схема «действие-результат» во всей своей красе. Жмешь здесь - получается вот это. А зачем жать? Да чтобы переменную создать.

Выводы по разделу

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

Соблюдены ли рекомендации манифеста? Нижеследующая принимается частично:

«Нежелательны «надо», «необходимо», «следует»». В части «следует» автор манифеста, уважаемый г-н Кагарлицкий, прямо противоречит требованиям п. 4.2.2 ГОСТ 2.105-95. «Надо» - нехорошо, «необходимо» - еще куда ни шло, а вот «нужно» - вовсе никуда не годится. Хотя шалят, шалят «маститые техписы»:

- Зачем нужно это

Харизматичный автор указанного выше заголовка, т.н. «технический писатель» всех времен и народов, является отцом-основателем «понятийно-чувственной (тупиковой)» ветви отечественного «техписовского сообщества». Фрагмент «руководства» того же автора:

- Каждому вору - возможность украсть

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

А уместна ли такая вот «шуточка» в руководстве пользователя? Иной User, по простоте душевной, еще и за решетку угодит, списывая ГСМ на заправку прицепа.

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

Принцип авторитетности изложения соблюден, хотя цель таковая и не ставилась.

Соблюдены ли рекомендации IEEE Std 1063-2001?

«Documentation shall explain the formats and procedures for user-entered software commands, including required parameters, optional parameters, default options, order of commands, and syntax... Examples should illustrate the use of commands... Documentation shall describe how to recognize that the command has successfully executed or abnormally terminated».

В целом - да. За исключением «Documentation shall explain how to interrupt and undo operation during execution of a command and how to restart it, if possible», поскольку для прерывания, отмены или повторного запуска операции достаточно сведений, которые пользователь может почерпнуть из руководств пользователя операционной системы. И нечего дублировать указанные сведения от руководства к руководству.

Копирование переменной (разъяснения)

Чтобы избежать многократного повторного описания одних и тех процедур, следует воспользоваться «возвратными» ссылками на предыдущие разделы (подразделы) руководства пользователя.

Для копирования переменной (выполнения указанной операции) следует:

  1. Выполнить процедуры 1 - 6 п. Создание (добавление) новой переменной. На рабочем столе будет отображено окно Variables;

    - Окно Variables с переменной proba
  2. Выбрать из списка переменную proba;
  3. Нажатием правой кнопки мыши в поле переменной proba вызвать (открыть) всплывающее меню и выбрать пункт Copy или нажать кнопку Copy. В первую позицию списка переменных будет добавления переменная Copy_of_proba;

    - Копирование переменной AuthorIT
  4. Закрыть окно Variables нажатием кнопки OK.

Удаление переменной (разъяснение)

Считаем, что AuthorIT Administrator не был закрыт.

Для удаления переменной (выполнения указанной операции) следует:

  1. Выбрать из списка переменную, подлежащую удалению (например, переменную Copy_of_proba);
  2. Нажатием правой кнопки мыши в поле переменной Copy_of_proba вызвать (открыть) всплывающее меню и выбрать пункт Delete или нажать кнопку Delete. На рабочем столе будет отображено окно

    - Окно удаления
  3. Нажать кнопку Yes. Переменная Copy_of_proba будет удалена из списка переменных. Окно Variables примет вид

    - Окно Variables с переменной proba

Что получилось в результате

Смотрите:
Переменные в AuthorIT

Переменные в AuthorIT

Смотрите:
Переменные AuthorIT - назначение
Переменные AuthorIT - состав
Использование переменных в AuthorIT
Действия с переменными AuthorIT

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

Переменные могут быть вставлены в тексты топиков AuthorIT для замещения кратким <ИМЯ_ПЕРЕМЕННОЙ> многократно повторно используемых:

  • фрагментов текста;
  • элементов графики;
  • файловых объектов;
  • параметров системы (дата, время, имя пользователя и пр.).

Описания переменных представлены полями:

  • variable - полем имени переменной (в текстовом формате);
  • default (value) - полем значения по-умолчанию (полем значения);
  • description - полем описания (в текстовом формате);
  • type - полем типа переменной (возможные значения - Text, List Of Values, File Objects, System);
  • style - полем стиля. Возможные значения сведены в Таблицу.

don't inherit

none

Buttons a

Emphasis a

Expanding Inline a

Menu Options a

Monospace a

Special Bold a

Subscript a

Superscript a

Symbols a

Winding Symbols a

AuthorIT Administrator обеспечивает возможность создания (добавления), копирования, удаления, назначения и редактирования (изменение полей описания) переменных (за исключением переменных System).

AuthorIT Administrator обеспечивает возможность изменения значений полей описания переменных (за исключением переменных System).

Имена переменных заключаются в угловые скобки, например <PROGRAM_NAME>.

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

Переменные AuthorIT - назначение

Переменные AuthorIT предназначены:

  • для хранения фрагментов текста, элементов графики, файловых объектов и системных переменных - многократно повторно используемых элементов информационного наполнения документов;
  • для замещения перечисленных выше элементов информационного наполнения короткими именами переменных в топиках AuthorIT;
  • для замещения имен переменных элементами информационного наполнения в публикуемых документах;
  • для публикации различных элементов информационного наполнения в различных версиях типовых документов.

Переменные AuthorIT - состав

В состав переменных AuthorIT входят переменные четырех видов:

  • Text;
  • List Of Values;
  • File Objects;
  • System.

Смотрите:
Переменные Text
Переменные List Of Values

Переменные Text

Значение переменной Text представляет собой строку, состоящую из набора символов (a-z, A-Z, _). Переменная Text может хранить (иметь) единственное значение.

Переменные Text предназначены:

  • для хранения фрагментов текста в виде значений переменных;
  • для замещения фрагментов текста короткими именами переменных в топиках AuthorIT;
  • для замещения имен переменных фрагментами текста в публикуемых документах;
  • для публикации различных фрагментов текста в различных версиях типовых документов.

Строка значения переменной Text может включать в себя от 0 до 2000 символов.

Переменные List Of Values

Значения переменных List Of Values представляют собой набор (список) строк, состоящих из набора символов (a-z, A-Z, _).

В отличие от переменных Text, переменные List Of Values могут хранить несколько значений (список значений). Текущим значением переменной может быть любой элемент из списка значений, выбранный пользователем с помощью AuthorIT Administrator.

Переменные List Of Values предназначены:

  • для хранения фрагментов текста в виде значений переменных;
  • для замещения фрагментов текста короткими именами переменных в топиках AuthorIT;
  • для замещения имен переменных фрагментами текста в публикуемых документах;
  • для публикации различных фрагментов текста в различных версиях типовых документов.

Строки значений переменных List Of Values могут включать в себя от 0 до 255 символов.

Использование переменных в AuthorIT

Использование переменных сводится к вставке имени переменной в текст топика AuthorIT. Для вставки переменной в текст топика AuthorIT следует:

  • запустить программу AuthorIT;
  • открыть требуемый топик;
  • выбрать требуемую позицию в тексте топика для вставки переменной;
  • выбрать пункт Insert главного меню AuthorIT;
  • в выпадающем меню указать пункт Variables;
  • в подчиненном меню выбрать требуемую переменную из списка.

В результате вставки в требуемой позиции текста топика будет отображена переменная в формате <ИМЯ_ПЕРЕМЕННОЙ>, например, 10 Май 2021 г. при вставке переменной System Long Date.

Действия с переменными AuthorIT

AuthorIT Administrator обеспечивает возможность создания (добавления), копирования, удаления, назначения и редактирования (изменение полей описания) переменных (за исключением переменных System).

Смотрите:
Создание (добавление) новой переменной
Копирование переменной
Удаление переменной

Создание (добавление) новой переменной

Для создания (добавления) новой переменной (выполнения указанной операции) следует:

  1. Запустить AuthorIT Administrator стандартными средствами операционной системы. В случае успешного запуска на рабочем столе будет отображено окно со списком наиболее часто используемых библиотек;

    - Запуск AuthorIT Administrator
  2. Выбрать из списка требуемую библиотеку;
  3. Нажать кнопку OK. На рабочем столе будет отображено окно Enter Library Password;

    - Окно Enter Library Password
  4. После выбора из выпадающего списка User name имени пользователя и ввода пароля в текстовое поле Password нажать кнопку Login. На рабочем столе будет отображено главное окно программы AuthorIT Administrator;

    - Главное окно AuthorIT Administrator
  5. Выбрать пункт Variables главного меню;
  6. В выпадающем меню выбрать пункт Maintain Variables. На рабочем столе будет отображено окно Variables;

    - Окно Variables
  7. Нажатием правой кнопки мыши в поле вызвать (открыть) всплывающее меню и выбрать пункт Add или нажать кнопку Add. На рабочем столе будет отображено окно Variable <> default settings;

    - Окно Variable default settings
  8. Ввести в поле Name (внутри угловых скобок) имя переменной (например, proba);
  9. Выбрать из выпадающего списка Type требуемый тип переменной (например, Text);
  10. Выбрать из выпадающего списка Style требуемый стиль (например, оставить по умолчанию);
  11. Ввести в поле Value текст значения переменной (например, проба пера);
  12. Ввести в поле Description текст описания переменной (например, Пробная переменная);
  13. Нажать кнопку Apply. Окно примет вид, изображенный на рисунке (ниже);

    - Окно Variable proba default settings
  14. Нажать кнопку OK. На рабочем столе будет отображено окно Variables, содержащее в первой позиции списка переменных вновь созданную переменную proba;

    - Окно Variables с переменной proba
  15. Нажать кнопку OK;
  16. Закрыть AuthorIT Administrator стандартными средствами операционной системы (при необходимости).
Копирование переменной

Для копирования переменной (выполнения указанной операции) следует:

  1. Выполнить процедуры 1 - 6 п. Создание (добавление) новой переменной. На рабочем столе будет отображено окно Variables;

    - Окно Variables с переменной proba
  2. Выбрать из списка переменную proba;
  3. Нажатием правой кнопки мыши в поле переменной proba вызвать (открыть) всплывающее меню и выбрать пункт Copy или нажать кнопку Copy. В первую позицию списка переменных будет добавления переменная Copy_of_proba;

    - Копирование переменной AuthorIT
  4. Закрыть окно Variables нажатием кнопки OK.
Удаление переменной

Для удаления переменной (выполнения указанной операции) следует:

  1. Выбрать из списка переменную, подлежащую удалению (например, переменную Copy_of_proba);
  2. Нажатием правой кнопки мыши в поле переменной Copy_of_proba вызвать (открыть) всплывающее меню и выбрать пункт Delete или нажать кнопку Delete. На рабочем столе будет отображено окно

    - Окно удаления
  3. Нажать кнопку Yes. Переменная Copy_of_proba будет удалена из списка переменных. Окно Variables примет вид

    - Окно Variables с переменной proba

Заключение

Умному достаточно. Какой смысл далее грузить читателя типовыми описаниями типовых процедур, если цель достигнута, а задача решена?

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

  • скачать и установить на свой компьютер триальную версию AuthorIT;
  • засечь время;
  • последовательно выполнить все процедуры, сведения о которых изложены в подразделах:
    • Создание (добавление) новой переменной;
    • Копирование переменной;
    • Удаление переменной.
  • посмотреть, сколько времени ушло на выполнение процедур.

Естественно, все получится, и автор настоящей статьи будет безмерно счастлив. Фрагмент руководства, разработанный с использованием предложенных приемов, «сработал» в руках пользователя, умеющего читать и возить мышью по рабочему столу. Сработал в руках и пионера, и пенсионера. Что и требовалось доказать.

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

Что ж, остается только элегантно сверстать руководство. Для элегантной верстки потребуется вставка произвольно выбранной картинки (например, колымаги), да только не выше (ниже, справа или слева), а непременно где-нибудь сбоку:

- Сбоку расположен пример простого отчета

- Последний вагон на север