На чем пишем документацию

finsoftrz

Хотел поинтересоваться, кто что использует для написания документации к приложениям. Сам я давно пользуюсь старой пятой версией help&manual плюс uvScreenCamera для снимков экрана и видео. Некоторые рекомендуют dr. Explain, российская разработка, стоимость легальной лицензии 15 тыр на год.

kreator

DreamWeaver + MS HTML WorkShop.

ingasoftplus

finsoftrz писал(а): 25 Январь 2025, 10:13help&manual

6

finsoftrz

Глянул Dr.Explain из-за разрекламированной функции анализа области экрана. Там смысл в том, что выбираем окно или произвольную область, программа анализирует ее содержание и вставляет в проект скриншот со ссылками на распознанные контролы, а под скриншотом размещает табличку под их описание. Остается ввести названия и сами описания. Это не совсем то, что хотелось, так как основное время при работе по подготовке инструкций и описаний уходит на набор текста. Но навело на идею встроить в приложение возможность сбора информации об окне с последующей вставкой в H&M.
Попробовал на entry полях. Для них я всегда делаю тултипы. Описание в мануалах обычно аналогично тултипу плюс дополнительные подробности. Таким образом, из промпта мы можем взять название реквизита, из тултипа его описание. В H&M можно делать вставки в xml представление раздела, поэтому сразу можем обернуть эти значения в xml теги с используемым стилем. Для примера такое окно.

: help1.png (10.11 КБ) 8314 просмотров

Формируем список используемых контролов.

После вставки в H&M сразу получаем все описания, а дальше можем уже дорабатывать.

Это экономит немало времени для справки по новым диалогам. Чаще бывает дополнение какого-то функционала в существующие. Поэтому прибил в шаблонах клавиши CtrlAltH, при нажатие на которые в буфер обмена помещается информация по контролу, на котором находится фокус.

Жизнь стала немного легче.

Игорь Столяров

finsoftrz писал(а): 28 Январь 2025, 8:15 информация по контролу, на котором находится фокус.

В принципе, есть ведь возможность показывать краткое описание контрола в строке состояния AppFrame.
Но если Вы не используете возможность самодокументации MSG(Текст), вполне можете размещать в ней
текст для выгрузки в H&M и т.д.

finsoftrz

Игорь Столяров писал(а): 28 Январь 2025, 13:02
finsoftrz писал(а): 28 Январь 2025, 8:15 информация по контролу, на котором находится фокус.
В принципе, есть ведь возможность показывать краткое описание контрола в строке состояния AppFrame.
Но если Вы не используете возможность самодокументации MSG(Текст), вполне можете размещать в ней
текст для выгрузки в H&M и т.д.

Я использую и msg, и tip. В tip несколько подробнее информация или такая же, как в msg. Поэтому она и передается для H&M.
Механизм этот можно расширять, например, я хотел еще и заголовки колонок list аналогично передавать. В теории можно и совсем все на автомат поставить, включая сохранение скриншота окна и отдельных контролов в png файлы. Но это не очень хорошо получается, когда-то давно пробовал похожий подход и отказался.
Как показала практика, самое нудное это когда смотришь на скриншот и переписываешь информацию с него в H&M. Или лезешь в app и пытаешься оттуда копировать. Неудобно и времени много теряется.

Игорь Столяров

На мой субъективный взгляд, вполне достаточно средств самодокументации контролов.
Иначе их описание сводится к "для добавления нового товара, откройте справочник товаров и нажмите кнопку ДОБАВИТЬ".

Есть смысл описывать практику применения, но она разнообразна и специфична ...

finsoftrz

Игорь Столяров писал(а): 28 Январь 2025, 14:00 На мой субъективный взгляд, вполне достаточно средств самодокументации контролов.

Я так и делаю. Tip на мое восприятие лучше, чем msg, последний просто для интерфейса копирую из tip и иногда сокращаю. Справка по F1 это пояснения по поводу реквизитов. Я ее больше для себя делаю, чтобы лучше видеть картину, не залезая каждый раз в код. Там заголовок раздела, кратко для чего нужно и где лежит (если подгружаемая dll), а далее список контролов и назначение (кроме стандартных контролов для всех окон). Слов паразитов типа откройте то и нажмите на это там нет. Скриншотов тоже нет.

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

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

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

ingasoftplus

finsoftrz писал(а): 28 Январь 2025, 15:11 что нужно еще описание бизнес-логики на концептуальном уровне

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

gopstop2007

finsoftrz писал(а): 28 Январь 2025, 8:15 Глянул Dr.Explain из-за разрекламированной функции анализа области экрана. Там смысл в том, что выбираем окно или произвольную область, программа анализирует ее содержание и вставляет в проект скриншот со ссылками на распознанные контролы, а под скриншотом размещает табличку под их описание. Остается ввести названия и сами описания. Это не совсем то, что хотелось, так как основное время при работе по подготовке инструкций и описаний уходит на набор текста. Но навело на идею встроить в приложение возможность сбора информации об окне с последующей вставкой в H&M.
Попробовал на entry полях. Для них я всегда делаю тултипы. Описание в мануалах обычно аналогично тултипу плюс дополнительные подробности. Таким образом, из промпта мы можем взять название реквизита, из тултипа его описание. В H&M можно делать вставки в xml представление раздела, поэтому сразу можем обернуть эти значения в xml теги с используемым стилем. Для примера такое окно.

help1.png

Формируем список используемых контролов.

help2.png

После вставки в H&M сразу получаем все описания, а дальше можем уже дорабатывать.

help3.png

Это экономит немало времени для справки по новым диалогам. Чаще бывает дополнение какого-то функционала в существующие. Поэтому прибил в шаблонах клавиши CtrlAltH, при нажатие на которые в буфер обмена помещается информация по контролу, на котором находится фокус.

Жизнь стала немного легче.

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

gopstop2007

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

finsoftrz

gopstop2007 писал(а): 29 Январь 2025, 14:27 Из своего опыта, максимально 5% пользователей читает хелп, проще набросать кнопок со ссылкой на ютуб, при нажатии сразу открывается видео.

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

gopstop2007

finsoftrz писал(а): 29 Январь 2025, 15:23
gopstop2007 писал(а): 29 Январь 2025, 14:27 Из своего опыта, максимально 5% пользователей читает хелп, проще набросать кнопок со ссылкой на ютуб, при нажатии сразу открывается видео.
В значительной мере из-за самого help. ...

Если бы, в основном из-за лени или не компетенции пользователей

К сожалению, как и при лечении, проще выпить таблетку, чем лечить причину.

finsoftrz

gopstop2007 писал(а): 29 Январь 2025, 15:57 Если бы, в основном из-за лени или не компетенции пользователей К сожалению, как и при лечении, проще выпить таблетку, чем лечить причину.

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

gopstop2007

finsoftrz писал(а): 29 Январь 2025, 16:13
gopstop2007 писал(а): 29 Январь 2025, 15:57 Если бы, в основном из-за лени или не компетенции пользователей К сожалению, как и при лечении, проще выпить таблетку, чем лечить причину.
В таких случаях можно только предложить повернуть доску на 180 градусов и попробовать залезть в шкуру пользователя. Люди примерно везде одинаковые, из этих реалий и надо исходить.

Из таких реалий и исходил, пользователю залезть читать и понимать или просто посмотреть ролик