Комментарии 7
Познавательно. Прокомментирую некоторые тезисы.
в наших руководствах пользователя представлены разделы о назначении программного обеспечения и основных операциях, которые в нем можно выполнить
Вообще это не требование ГОСТ 19.505 или 19.506, это требование здравого смысла при создании любой инструкции. Более того, именно стандарты ЕСПД в отношении руководств, на мой взгляд, довольно бесполезны: по ним невозможно понять, как рационально структурировать информацию на уровне ниже заголовков верхнего уровня, а ведь там как раз самое интересное и начинается.
В разделе об основных операциях перечисляются основные операции [...]. Этот раздел позволит разглядеть за интерфейсом не несвязанные между собой компоненты, а маршруты из набора действий.
Тут очень важно отметить, что основные операции — это часто в мире программы, а маршруты из набора действий — всегда в мире пользователя. И если операции можно понять прямо из интерфейса программы, то маршруты видны только если решать пользовательские задачи.
...мы стараемся создавать внутреннюю связь между разделами при помощи перекрестных ссылок. Это не всегда получается...
А можете пояснить, когда именно не получается поставить перекрёстные ссылки? В веб-версии ведь ссылку можно воткнуть на любой текст, а в печатной версии — на страницу с текстом.
Если по одной из затронутых тем подробная информация содержится в другом документе, мы уточняем это с указанием наименования документа.
А вот это отличный подход — класть информацию только в одно место, и там её поддерживать.
для руководства администратора наличие большого количества технических деталей считается нормой, в руководстве пользователя их не должно быть много
Боюсь, «много» — не то слово. :) В руководстве пользователя подробностей должно быть точно столько, сколько достаточно, и ни слова больше. Но определить, how much is too much — непросто, да.
перечисление компонентов интерфейса стоит начинать с основного компонента, а описание компонента интерфейса — с описания его назначения
Это не всегда так. Например, описание меню вполне разумно дать сверху вниз и вглубь, если есть вложенные пункты. Описывать однородные элементы интерфейса тоже разумно слева направо сверху вниз, как их видит пользователь.
документация позволяет уменьшить затраты на интеграцию нового продукта в компании
...а заодно снижает нагрузку на хелпдеск, когда и если он есть. Но вот именно что учебную ценность руководства пользователя я бы не преувеличивал: в зависимости от назначения и сложности продукта может потребоваться и учебник, и серия видеороликов, и справочники по решению типовых задач.
Спасибо за обратную связь. Было интересно услышать мнение со стороны и дополнить свое представление о том, как должно быть. Про перекрестные ссылки: физически, конечно, их получается, указывать. Скорее в некоторых случаях, когда можно обойтись без них, стараемся обойтись. При внесении изменений в документацию они могут слетать, а при большом количестве ссылок одну такую сломанную можно не заметить и не обновить.
А если есть ссылки, без которых обойтись нельзя, но при обновлении они тоже могут слететь, всё равно ведь придётся отлавливать? :) Странная ведь позиция. Ну то есть я знаю, что ссылка может слететь не совсем, а вести в неправильное место, и это выловить действительно трудно, но надо ли тогда вылавливать? По большому счёту ведь пользователи уже довольно давно свыклись с тем, что не всё работает идеально, и баги в документации тоже не то чтобы допустимы, но простительны: нашли — исправили, обычное дело.
Да, все равно придется отлавливать. И если документацию обновляет один человек и он в состоянии запомнить, что где должно быть, то в этом нет проблемы. Но если одну и ту же документацию обновляют разные технические писатели, и вместе они работают с большим количеством документов, то возможны ситуации, когда ссылка сломалась, а технический писатель не знает или не помнит, куда она должна вести.
Не придирки ради, но пользы для.
На картинке с оглавлением выезд строки в зону номера страницы выглядит некрасиво — особенно это касается пункта 4.7.2, в котором на следующей строке висит единственное оторванное от фразы слово, а отточие до номера страницы не воспринимается как часть строки. Рационально было бы переносить строку раньше. Я для этого пользовался неразрывными пробелами, но, вероятно, есть более элегантное решение на основе настройки табуляции в стилях.
На картинке с таблицей 9 в первой строке таблицы информация дана избыточно: если можно разместить 1, 2 или более компонентов, значит, можно разместить 1 и более. Возможно, в таком дублировании есть какой-то смысл, невидимый с дивана, но с дивана такое дублирование информации выглядит забавно (и раздувает таблицу).
На картинке с заголовком «2.1 Функция Оперативный Контроль» всё прекрасно, но почему бы не различать на письме служебные слова и названия? Например, вот так: «Функция Оперативный Контроль» или «Функция Оперативный Контроль». Или даже «Функция Оперативный Контроль» Немного, но улучшит читаемость.
Согласна с комментариями к изображениям с пунктом 4.7.2 и с таблицей 9. С комментарием про выделение служебных слов или названий — скорее, нет. В основном тексте названия у нас выделяются жирным, путаницы не происходит. Мы не выделяем отдельные слова курсивом в заголовке по редакционной политике. На мой взгляд, это избыточно.
Редполитика — это святое. На мой вкус выделять одинаковые сущности надо одинаково везде, включая заголовки. Я объясняю это тем, что читатель прилагает меньшие когнитивные усилия по распознаванию того, что есть что в заголовке, а мы заодно приобретаем компенсацию грамматически несогласованных предложений. Вот даже пример тот же: предложение «Функция Оперативный Контроль» звучит просто как набор слов, и что из этих слов искать в интерфейсе (и что не искать) из написания не следует, а могло бы. Это не про путаницу, это про внимание к деталям и мелочам.
Но таки да, редполитика — святое.
Пользовательская документация как путеводитель по продукту