Клуб технических писателей

Подробная расшифровка полей

bryston
24 июля 2015, 07:15

Коллеги, подскажите, когда Вы описываете формы с полями ввода или таблицы, насколько подробно даете расшифровку полей?

Поясню свой вопрос:

  • Ст. отп. — станция отправления;
  • Ст. отп. — наименование станции отправления;
  • Ст. отп. — наименование станции отправления, например Москва-Павелецкая. 

В приведенном примере вроде бы можно найти "золотую середину", но бывают случаи, когда поле содержит только часть той или иной информации, например, в поле Договор отображается только номер договора (пусть 256), хотя пользователь при заполнении данного поля выбирает из справочника значение, скажем, Договор 256 / РФ - международный от 15.12.2014:

  • Договор — договор с клиентом;
  • Договор — номер договора с клиентом;
  • Договор — номер договора с клиентом, например 256. 

Указание значения в качестве примеров позволяет пользователю представить то, что отображает поле, особенно если документация является первым вводным уроком для нового сотрудника. Написать, что поле содержит период значит не сказать ничего, а вот уточнить это примером — 22.12.2014-22.01.2015 — совсем другое дело.

Заранее спасибо за ответы!

12 комментариев
Кристина
27 июля 2015, 13:16

Не поняла про поле "Договор". В действительности это выпадающий список?

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

Кристина
28 июля 2015, 11:23

То есть он выбирает откуда-то "Договор 256 / РФ - международный от 15.12.2014", а в поле остается просто "256"?

Да, в беседах с пользователями некоторые из них рекомендуют точнее описывать, что отображается в поле; с другой стороны такая детальность может очень усложнить текст, например, "Наименование статуса записи при импортировании данных" можно заменить на "Статус импортированной записи".

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

Договор — номер договора с клиентом, например 256. 

Ощущение, что нужно самому ввести цифры.

То же самое и с вариантом

Ст. отп. — наименование станции отправления, например Москва-Павелецкая. 

Ощущение, что по каким-то там правилам надо ввести именно "Москва-Павелецкая", а не просто "Павелецкая".

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

Спасибо, Кристина! А как у Вас принято описывать перечень полей для заполнения? Я предпочитаю таблицу, в которой указаны поля, их расшифровка и способ заполнения; вот при описании способа заполнения и указывается что и как, например, выбрать из списка или ввести вручную.

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

Спасибо, Кристина! Но это только частный случай, который Вы описали, и он никак не может помочь решить вопросы, когда, например, продукт не документировался долгое время, основные разработчики уволились, оставив названия полей "непонятными" или техпис - фрилансер, которому поставили задачу и все!!! С полями вопрос, скорее всего, можно отнести к теме о замкнутом интерфейсе: менять флажки нельзя, но очередность А1-А2-А3 присутствует :)

После Вашего сообщения специально посмотрел настроечные поля в редакторе MS Word, и скажу, что очень много там полей, которые в явном виде должны быть описаны в документации, так как интуитивно или по названию понять их смысл трудновато (хотя сам их смысл знаю, работаю с этим редактором уже очень давно). Удачи!!!

Безусловно это частный случай, я просто отвечала на ваш конкретный вопрос.

Кристина, могли бы Вы дать ссылку на тот или иной он-лайн документ Яндекса, в котором есть описание полей для пользователя, скажем, заполненение определенной экранной формы?

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

А так, каталог документации тут: https://yandex.ru/support/

Спасибо!