Среда проектирования пользовательского интерфейса

[Артем]

 День добрый.

Вопрос в целях самообразования:

 Есть две задачи: спроектировать пользовательский интерфейс и написать руководство пользователя (в части интерфейса).

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

 А есть ли средство, которое позволяет следующее:
 
 нарисовать интерфейс, а потом на основе нарисованного интерфейса сгенерить скелет описания этого самого интерфейса, например в ворде?

 Так будет хоть какая-то гарантия, что я не забуду описать какой-нибудь пункт менюшки, который добавился в "последний момент", и главное, вводить информацию об интерфейсе в комп придется один раз (на этапе рисования), а не два как было раньше (рисование + набивание Руководства)
 

[Alf]

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

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

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

[Гром]

Артем, на мой сугубо личный взгляд, существующая модель интерфейсов порочна. Разрабатывалась она довольно давно и первым, применившим подобное решение был Питер Нортон. У него уже сперли Вилли всякие идею меню и засунули в прокрустого ложе теории эргономики.

А вот среств параллельной разработки и описания не существует. Причина - сложность формализации описания. Альф прав в одном, скрины вторичны, смысл описания не в них. Ведь основной целью ГУИ есть предоставление пользователю удобной возможности управлять неким процессом.
Этот процесс и нуждается в формальном описании.

Напиши изначально описание процесса и его управления, и уже на базе этого описания создай интерфейс. Тогда и не придется дважды описывать одно и то же.

[Dimka]

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

По методической схеме:

1) Задача, стоящая перед пользователем.
2) Способ решения задачи при помощи программы (последовательность операций с пользовательским интерфейсом).

И так для каждой штатной задачи. Задачи могут быть иерархически упорядочены.

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

[Гром]

dimka, +1 совпадаем

[Артем]

  К сожалению, у нас в конторе до сих пор использовалась "модель интерфейсов" та, что я описал выше, т.е. "картинка"-> "код"->"Руководство". У меня есть сильное подозрение, что она еще "более порочна"

 Скрины, конечно, вторичны, но мне ведь нужен язык, на котором я должен объяснить заказчику (пользователю) про этот самый процесс и его управление. До сих пор я использовал два способа:
  1. Общие слова.
            Например:  Программа имеет возможность "сделать Вас счастливым".
  2. Часть Руководства
           Например:Если вы в меню "файл" (тут изображение меню "файл") выбирите пункт "Счастье" (тут изображение путкта "Счастье"), тогда появиться диалог "Счастье" (изображение этого диалога), в котором есть кнопка "Счастье Мне", нажав на которую будет Вам счастье.

В качестве третий альтернативы был предложен язык UML (+технология, под которую он заточен). Лично мне UML и его идеалогия приглянулись, т.к. это и есть язык, который, в отличии от "простого русского" не допускает разночтений, и который может быть понятен как заказчику, так и разработчику (ну и плюс ряд полезностей которые мне тоже приглянулись).

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

 Поэтому я и пытался найти подходящий "язык общения". Пока таким "языком" являются скриншоты несуществующей проги.

 
  

 

 

[Артем]

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

  Согласен, но ведь все равно это сведется к "для решения задачи 1--нажмите большую красную кнопку".

  А потом заказчик (начальник, пользователь) говорит: "хочу не красную, а синюю..."

я и хочу услышать эту фразу ДО написания проги, а не после

[Артем]

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

Ох!
а это еще один больной вопрос который маячит у меня на горизонте:
 
 как бы автоматизировать разработку этих документов: Бумажного руководства и интерактивной справки, так что бы написать один документ, а на основе него создать все остальное

а то ведь опять получается одно и тоже "забивать" два раза: сначало в Бумажного руководство, а потом в справку. И ведь стопудово  эти два документа будут различаться  , и будут звонить юзеры с вопросом "Чему верить?"
 
 

[Dimka]

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

В качестве третий альтернативы был предложен язык UML (+технология, под которую он заточен). Лично мне UML и его идеалогия приглянулись, т.к. это и есть язык, который, в отличии от "простого русского" не допускает разночтений, и который может быть понятен как заказчику, так и разработчику (ну и плюс ряд полезностей которые мне тоже приглянулись).

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

 Поэтому я и пытался найти подходящий "язык общения". Пока таким "языком" являются скриншоты несуществующей проги.

Скажем так, для показа того, "как это всё примерно будет", пишутся прототипы программ - каркас системы с нереализованными функциями. Особенно удобно, если функции в программе между собой несвязаны (например, выбор любой функции из меню в произвольном порядке).

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

С другой стороны, рассказ о том, что пользователь узнаёт о процессе из документации к программе, есть свидетельство какой-то анархии в проекте. Если ты читал ГОСТы по АСУ, то там (и считаю это плюсом) чётко разграничиваются сферы деятельности по внедрению информационной системы в работу предприятия: одно дело - программная система, другое дело - организация работ. Если автоматизация предполагает реорганизацию бизнес-процессов, то эта реорганизация находится в компетенции руководства, а не программиста. Если же руководство само не знает, какой процесс оно строит, и узнаёт это лишь из скриншотов программы - боюсь, плохо такой проект закончится. Какой же это "заказчик", когда он не описал, чего заказывал, и не знает, какой функционал будет в программной системе? Прямо как в сказке: "Поди туда, не знаю куда - принеси то, не знаю что."

Т.е. в начале строятся две модели предметной области: "как есть" и "как должно быть", понимание этих моделей должно быть у всех ответственных за проект (как с технической, так и с организационной стороны) лиц. И это понимание должно быть отражено в проектной документации - в техническом задании (в случае небольшого проекта) или в техническом проекте (в случае большого проекта). Но никак такие вещи не должны входить в руководство пользователя. Руководство пользователя содержит описание способов использования программы, а не "космические" темы о целях проекта или организацию работы в переходный период, или как пользователю переучиться с использования старой версии на новую. Всякие методические руководства этапа внедрения - это отдельный комплект документов, действующих ограниченное время переходного периода, а руководство пользователя - это "вечный" документ, сопровождающий программную систему в течение всего периода её эксплуатации, и, желательно, всегда актуальный.

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

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

[Артем]

С другой стороны, рассказ о том, что пользователь узнаёт о процессе из документации к программе, есть свидетельство какой-то анархии в проекте

 Всё немножко не так (хотя эта самая анархия конечно же присутствует:( ), это не пользователь узнает о процессе, а программист. У нас, наверное, не очень стандартная ситуация: заказчик, он же пользователь, он же начальство -- на порядок лучше разбирается в этом самом процессе, чем разработчики.

 ТЗ, и даже тех. проект есть, более того уже даже существует работающее ПО которое содержит более 90% функционала, описанного в этих документах. Но это самое ПО уже никого не устраивает. Почему? Из-за интерфейса. Хотя он (интерфейс) был описан в тех. проекте. Но был описан именно так, как вы говорите: с точки зрения функционала.
 
 Интерфейс существующего ПО позволяет выполнять весь (точнее почти весь) требуемый функционал, но работать с этим интерфейсом очень и очень не просто

 
 А что касается моего упоминания руководства пользователя, так это я просто подумал: "Почему бы не оформить описание интерфейса (на этапе проектирования) в виде этого самого Руководства? Так, глядишь, и интерфейс "застолбишь", и начальству будет что показывать в ответ на "хочу большую синюю кнопку" ".

 
 

[Dimka]

Всё немножко не так (хотя эта самая анархия конечно же присутствует:( ), это не пользователь узнает о процессе, а программист. У нас, наверное, не очень стандартная ситуация: заказчик, он же пользователь, он же начальство -- на порядок лучше разбирается в этом самом процессе, чем разработчики.

И что, программисты "гадают", какой интерфейс понравится заказчику?

В данном случае каждый независимый бизнес-процесс нужно формально описать (например, в виде алгоритма (если алгоритм подходит для описания)). Формально в данном случае - не означает на языке программирования или при помощи UML, это означает, что в описании на обычном языке обычными словами должны быть учтены все ньюансы бизнес-процесса, и описание должно быть упорядоченным. И чтобы после никаких: "А, забыл это особый случай, там вот так..." Причём если описание производится с употреблением неких терминов, эти термины должны быть выписаны в отдельный словарик, и должно бытьепроконтролировано, чтобы эти термины всеми понимались одинаково. Вот это и есть "общий язык". С одной стороны - всё описано словами, понятными начальству, с другой стороны, всё достаточно упорядочено, чтобы программист мог работать.

Исходя из формальных описаний можно уже оптимизировать пользовательский интерфейс. По сути эта деятельность сводится к выявлению точек ввода/вывода информации при проведении бизнес-процесса и описыванию необходимой для решения задачи структуры входящих и исходящих информационных потоков (обычно для описания используют БНФ). И уже для каждой такой точки разрабатывается удобный интерфейс пользователя, чтобы:
- отобразить всю информацию, которая нужна для выполнения действий оператором,
- собрать всю информацию, которая нужна для продолжения работы,
- если какая-то часть информации нужна всегда - показывать её сразу, если какая-то часть нужна иногда - упрятать её в дополнительные формы.

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

Несколько непонятно, что перестало устраивать: только интерфейс пользователя или в том числе уже имеющийся функционал? Как может интерфейс, построенный на основе функционала, стать (а не быть) плохим? Либо он был плохой изначально (тогда странно, почему уже не устраивает), либо функционал перестал удовлетворять новым потребностям (тогда дело не в интерфейсе). Интерфейс, изначально устраивавший пользователей и построенный на основне функционала, связан с функционалом так же, как текст связан с информацией, которую этот текст несёт. Если текст стал непонятен, то можно констатировать смену контекста интерпретации текста. Если интерфейс стал казаться плохим, то скорее всего изменились требования к функционалу (системный контекст работы ПО) - пользователи необоснованно начали ожидать от ПО того, что в нём не было заложено изначально, и у пользователей не оказалось никаких возможностей использовать существующее ПО новым способом.

P.S. Что-то тема от темы уплывает

[Артем]

P.S. Что-то тема от темы уплывает

Ага ,  впрочем, Альф уже ответил на первоночальный вопрос.

Как может интерфейс, построенный на основе функционала, стать (а не быть) плохим?

Если такого функционала не было (вообще), тогда при его появлении основное внимание как раз к функциональным возможностям программы. Главное то что программа может это сделать, а не то как она это делает. Теперь важным стало как она это делает. (а делает она это очень не удобно )   

[Alf]

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

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

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

[Гром]

Артем, во первых, обрати внимание на путь  ТЗ-Дизайн-Ревью-Исправленный дизайн-Пост ревью-девелопинг-тестинг-написание хелпов и руководств.

В этом пути есть три пункта, которых в твоем случае нет, но которые вполне решают вопросы синекрасных кнопок.

Дизайн - ты должен писать еще до появления вопроса о кнопках и самое главное - дизайна может быть два Верхнего уровня и нижнего уровня.

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

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

[Гром]

Например, если по сценарию пользователь сначала должен зарегистрироваться в системе, а затем пользоваться ей, очевидно, что в первую очередь должна появиться форма регистрации для ввода учетной записи и пароля.

Жуть какая. Изначально должна появляться форма входа в программу, так как регистрируюсь я один раз, а вхожу постоянно.

При помощи рефакторинга можно сначала привести архитектуру к нужному виду,

Рефакторинг - улучшение структурированности кода программы.
Интересно, зачем применять рефакторинг, когда речь идет о фазе стартового проектирования еще до начала написания кода?


Далее все тоже самое, ихзменение и переработка сценариев и проч. и подобное.
Типичный теоретический подход к ООП.

[Dimka]

Типичный теоретический подход к ООП.

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

[Артем]

  Дизайн - ты должен писать еще до появления вопроса о кнопках и самое главное - дизайна может быть два Верхнего уровня и нижнего уровня.

 В первом случае ты опишешь общую структуру и алгоритм - который должен иметь и формы интерфейса. Во втором - весь интерфейс.

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

[Гром]

dimka, опять не соглашусь. Теория и практика вещи очень разные и по сути иногда противоречат друг другу. Слишком большое время на теоретическое проектирование сегодня тратить никто не будет. Ищем оптимальный подход с минимумом временных затрат и с максимальным соответствием модели теоретической к реальному финальному продукту.

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

Затем ты проэктируешь продукт. Я могу сказать, что даже если продукт имеет ГУИ или простенький текстовый интерфейс изначально интерфейсные воздействия моделируются в дизайне. Т.е. при написании пользовательско-зависимой программы по типу "нажми на кнопку получишь результат" дизайн низкого уровня включает в себя описание всех возможных реакций и их реализацию в блоках.

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

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

Причем учти - переработка идет дизайна верхнего уровня, а не нижнего.

[Dimka]

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

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

Я для себя определяю архитектуру и дизайн ПО (разница между ними в степени подробности описания системы) как функциональную структуру системы. Качество архитектуры связано с некоторыми свойствами: степенью связности элементов системы; тщательностью разделения на уровни абстракции; минимальности количества элементов системы, необходимых для достижения максимального разнообразия достижимых целей существования системы; концептуальной простотой каждого уровня абстракции. В результате хорошая архитектура позволяет модифицировать имеющуюся систему с минимальными трудозатратами

Ищем оптимальный подход с минимумом временных затрат и с максимальным соответствием модели теоретической к реальному финальному продукту.

Моя фраза относилась лишь к тому, что ООП - это частность.

Слишком большое время на теоретическое проектирование сегодня тратить никто не будет.

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

[Гром]

dimka,

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

С одной стороны ты прав, теория и практика начинают сливаться - если говорить о проектировании.
Но, я не согласен с общей формулировкой вопроса
Давай разберем пример - рефакторинг. Термин в общем и целом означает простую переделку программы, дабы ее улучшить.
Когда я учился - термина такого небыло. Было для работы с скоростью и производительностью употребляли слово тюнинх
Для простой переделки, употребляли термин доводка, или "вылизывание кода" или говорили - "будем менять структуру". Потом придумали умное слово.

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

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

Практика - все равно остается работой с "тублерами". Только тумблеры стали мышкой, или кнопками клавиатуры.

А в общем - это уже оффтопик, надо идти с темой в общение

[Sla]

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

Сделать описание интерфейса и при этом не приложить каких-либо усилий изначально - накладная штучка.
 
офф
И зачем иногда при поиске специалистов пишут - требуется technical writer?

[Артем]

Спасибо всем большое за активное участие . Большую часть моих "внутрених портиворечий" эта тема сняла

Остался еще один практический вопрос:

Ох!
а это еще один больной вопрос который маячит у меня на горизонте:
 
 как бы автоматизировать разработку этих документов: Бумажного руководства и интерактивной справки, так что бы написать один документ, а на основе него создать другой

а то ведь опять получается одно и тоже "забивать" два раза: сначало в Бумажного руководство, а потом в справку. И ведь стопудово  эти два документа будут различаться  , и будут звонить юзеры с вопросом "Чему верить?"

[Alf]

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

[Dimka]

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

Причина одна - качество документа. Под качеством в частности предполагается удобство использования документа (usability). Использование документов типа руководств происходит в двух "режимах": ознакомление - последовательное чтение, поиск справочных данных - случайный чтение разделов и параграфов документа. Из обоих случаев вытекают противоречивые требования к документу. Одним из часто практикуемых решений является: электронная версия в формате справочника, бумажная версия в формате учебника. Можно попробовать их объединить, но результат будет хуже для обоих случаев, хотя экономятся трудозатраты на подготовку документа.

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

[Alf]

Причина одна - качество документа.

А кто сказал, что онлайн-справка непременно должна обладать низким качеством?

Можно равняться на MSDN. Хочешь - выбирай интересующую тему и читай подряд. Хочешь - броди по гиперссылкам, пока не забудешь, откуда начинал. Хочешь - нажми в той же Studio кнопку F1 и получи контекстную справку. Не помню случая, когда я обратился бы к MSDN с реальным вопросом и остался без ответа.

[Гром]

Онлайн справка - не руководство.
Справка - каталогизированный массив данных о отдельных действиях.

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

[Dimka]

А кто сказал, что онлайн-справка непременно должна обладать низким качеством?

Под "бумажным" руководством я имел в виду книгу/статью/брошюру для последовательного чтения. Не имеет значения, напечатана ли она на бумаге или хранится в каком-нибудь PDF или даже CHM-формате в электронном виде. Разница в форме, в способе подаче материала, в стиле.

Для справок со случайным доступом к справочным статьям характерно описание конкретных действий с пользовательским интерфейсом, как Гром и сказал. Каждая такая статья часто имеет обилие ссылок на статьи о смежных действиях. Такой документ последовательно читать невозможно - материал упорядочен по элементам интерфейса пользователя или по алфавиту ключевых слов. В нём отсутствует систематическое описание функционала приложения - то, что должно быть в руководстве. Нет логического начала и продолжения. Доступ к справочным статьям осуществляется чаще всего по кнопке F1 или по клику на кнопке "Справка" - открывается зависящая от контекста статья.

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

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

Можно равняться на MSDN. Хочешь - выбирай интересующую тему и читай подряд. Хочешь - броди по гиперссылкам, пока не забудешь, откуда начинал. Хочешь - нажми в той же Studio кнопку F1 и получи контекстную справку.

MSDN в твоём описании - это лишь "движок". А мы говорим о контенте и его форме. В MSDN нет такого, что одна и та же статья открывалась бы по F1 при курсоре, стоящем на методе класса, и описывала бы целую технологию. Это всегда разные статьи, написанные разными людьми в разном стиле, акцентирующие внимания на разных вещах. Мы же здесь говорим о желании создать один документ в один приём без повторов, и чтобы этот документ был бы удобен в двух указанных "режимах" работы с ним. Такое почти всегда невозможно.

[Alf]

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

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

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

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

[Артем]

Мы же здесь говорим о желании создать один документ в один приём без повторов, и чтобы этот документ был бы удобен в двух указанных "режимах" работы с ним.

Ага, именно об этом. Или хотя бы о том, как один документ преобразовать в другой.

Вот был предложен вариант(пример с MSDN):
 сделать так, что бы один документ был подмножеством другого....


В общем, резюмируя:

  (ctrl+с)  + (ctrl+v) -- спасёт "отца русской демократии"

[Dimka]

(ctrl+с)  + (ctrl+v) -- спасёт "отца русской демократии"

Не то чтобы спасёт, но от части работы избавит.