iscrafmНевозможность отдельно взятого браузера под windows обработать backslash к тщательности документирования конечно же не относится. По содержанию что не так?
Хм. Простите, это все еще Вы, или логином пользуются несколько человек? Странно видеть несколько ответов на одно и то же письмо :)

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

Конкретных вопросов можно придумать достаточно много, но они вряд ли будут особо значимыми, поскольку опираются на незнание принятой у вас технологии работы, общей структуры документации итп. Сугубо для примера: http://www.iscrasoft.com/KSPHTML/Reports/Report1.html

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


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


Описание параметра pRDate неудачно


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


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


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


Отчет вроде как за период, а в параметрах присутствует только начало периода. Возникает вопрос - то ли используются стандартные периоды? То ли за период до текущей даты? То ли pRDate - это конец периода? Ответа на этот вопрос не видно.


Не видно информации о вариативности отчета. Например - если не указать pWhId (указать null), получу ли я информацию по всем складам или получу пустую выборку?


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


Ну а те описания, которые предусмотрены, почти везде пустые либо стандартные (не несут новой информации по сравнению с именем параметра).

Итого - по моим ощущениям, на этой странице есть один атом полезной информации: она позволяет выяснить, что реализация отчета "Движение номенклатуры за период" называется kspInventoryItemMoveSummary. За всем остальным, похоже, придется лезть раскапывать этот ksp. Также убивает практическое отсутствие навигации (три кнопки, мягко говоря, недостаточны) - для эффективности работы со справочной информацией (а вроде как имелась в виду именно она) это губительно.

ShtockА если отчеты делаются на основе данных сразу же нескольких баз?
Хм. Брать Data Dictionaries этих баз, вестимо.

ShtockГде,например,мне в Access в явном виде взять data dictionary
Не готов судить. Если его там нет - скрепя сердце, сделать велосипед персонально для этой базы. Но сами понимаете, частные недостатки следует ликвидировать на частном же уровне, не трогая общих решений.

ShtockУ нас,например,некоторые отчеты с помощью Business Objects формируются по нескольким БД одновременно.
Я бы сказал, это вполне типичная ситуация. Следующий шаг - это создание DWH под отчетность.

iscrafmВообще мне тяжело понять почему Вы так взъелись :)
Я нисколько не взъелся. Я ответил на заданный Вами вопрос, причем будучи в достаточной степени уверенным, что ни к чему конструктивному этот ответ не приведет.

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

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

iscrafmНажмите. Серьезные системы скажите, я тоже понажимаю, чтобы синхронно было и был предмет для общения.
Хм. Боюсь, у меня сейчас нет под рукой внедренного OEBS :)

iscrafm softwarer
Для отчета я бы ожидал увидеть описание не только параметров, но и выводимых результатов.


Установите систему и увидите. Или Вы хотите увидеть содержание фильма не вставив диск в проигрыватель? Это документация по проекту, а не рекламная листовка. нужен проект естественно.
Хм. То есть Вы хотите сказать, что увидев в отчете колонку, допустим, "Цена", я должен телепатически догадаться, какая именно это из тех N цен, которые поддерживаются в системе?

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

iscrafm softwarer
Я бы ожидал увидеть перечисление первичных источников данных, линки на них (провайдер, судя по имени, заточенный под конкретный отчет, вряд ли является таковым)


Он является таковым
То есть, Вы хотите сказать, что в системе есть таблица "Движение номенклатуры за период Summary" и провайдер фактически является select * from ЭтаТаблица?

iscrafmЭто проблемы автора проекта. Вполне возможно. К системе документирования не имеет отношения.
Не согласен. Это примерно та же позиция, что и "Есть отличная книга Библия, а то, что начитавшиеся ее творили, к теории уже отношения не имеет".

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

iscrafmОтчет на который Вы обратили внимание запускается по "ссылке". Разобраться имея проект и его интерактивное описание на самом деле просто. Я же привел только пример описания, ссылок на проект, базу данных и др. элементы системы не давал. Вопрос в такой постановке просто не стоял. А в связке они дают единое целое.
Хм. Я в принципе верю в такую ситуацию, о чем сразу и сказал - что желаемые Вами конкретные претензии к содержанию могут оказатья неудачными из-за неполной информации.

Однако, пока что я так и не понял, чем "имея проект и его интерактивное описание" разобраться проще, нежели просто "имея проект".

iscrafmЭто не отображаемый в интерфейсе параметр. Думаю термин "скрытый" достаточно однозначно определяет его
Пожалуйста, уточните, правильно ли я понял:

- в интерфейсе вызова отчета (форме параметров или чем-то аналогичном) пользователь вводит значения pRDate, pWhId, pStartDate, pItem. pWhId и pItem, полагаю, выбираются из справочника

- неизвестно откуда подставляется значение pItemName; пользователь его не видит, но в отчет оно уходит.

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

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

softwarer Отчет вроде как за период, а в параметрах присутствует только начало периода. Возникает вопрос - то ли используются стандартные периоды? То ли за период до текущей даты? То ли pRDate - это конец периода? Ответа на этот вопрос не видно.


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

iscrafmВсе таки хотелось бы по существу
По существу: как минимум, эта система документации ничего не стоит без толкового наполнения человеком. То есть автоматизация идет в лес.

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

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

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

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

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

iscrafm Notes есть абсолютно везде!
Не вижу . А учитывая, что в куче мест, например в описании, стоит "(не указано)" или пустота, либо стиль документации неоднороден (пустая секция notes не генерится), либо ее просто не предусмотрено.

В любом случае : если Вы привели неудачный пример - смените его и приведите удачный. Или - получите ответ на то, что Вы просили: "По содержанию что не так?".

P.S. Говорил же, что конструктива не выйдет.

iscrafm
softwarerВозникает впечатление, что эффективнее сразу лезть в первичку и искать комментарии там.
# Ну а те описания, которые предусмотрены, почти везде пустые либо стандартные (не несут новой информации по сравнению с именем параметра).

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

iscrafm softwarerЗа всем остальным, похоже, придется лезть раскапывать этот ksp.
А Вы думали раскопать это без этого ksp?
Я думал, что цель документации - убрать необходимость лазить в исходники по любому чиху; свести в одном месте в удобной для работы форме наиболее нужную информацию по данному объекту.

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


iscrafm softwarerТакже убивает практическое отсутствие навигации
А кнопки браузера Вы не считаете :)
Кнопки браузера я не считаю. Этак придется сказать, что и в бумажных книгах присутствует развитая система навигации.

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

iscrafmА Вы запустите html-help, ради интереса. любой.
Хм. Открыл хелп винды. Набрал в строке поиска "Беспроводная сеть", выбрал "настройка клиентов беспроводных сетей". Подсчитал - в этом окне у меня есть 33 ссылки для перехода к связанной информации.

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

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

ShtockПросто момент то в чем состоит:не в каждом data dictionary есть комментарии,а для покупных продуктов даже если они есть - разработчики специально их не заполняют (затирают),а хочется при изготовлении отчетов иметь названия полей по-русски/по-китайски/по-нужному языку.
Хм. Ну так взять и заполнить :) Если же комментариев не предусмотрено - снова приходим к "конкретная реализация data dictionary отсутствует или плоха", то есть к частному случаю, который таки приходится лечить.

Впрочем, стоит отметить, что в начальном посте речь шла о типах-размерах полей и той информации, которая наверняка есть в словаре.

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

iscrafmДаже можно по ссылкам ходить,
Не затруднит ли Вас указать документы со ссылками в диапазоне http://www.iscrasoft.com/KSPHTML/Reports/Report1.html .. http://www.iscrasoft.com/KSPHTML/Reports/Report60.html ? И сказать, сколько их там?

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

iscrafmТогда даже не знаю как ответить.
Хм. Признаться, это меня не удивляет. Потому как я и сам пока не вижу ответа.

iscrafm softwarerНа практике есть я - гипотетический пользователь системы. И если разработчик приносит мне плохую документацию, мне плевать, вина ли это автора проекта, системы документирования или черта лысого - мне важен факт
Пользователям приносят Руководство пользователя . С какого боку ему вдруг понадобилась документация по проекту разработки .
Попытка придраться к словам - это максимум? Ответа по сути не планируется?

iscrafm softwarerЕсли значение параметра берется из справочника - система документирования автоматически, без малейших усилий человека должна проставить ссылку на этот справочник. Примерно так же, как при наличии в таблице внешнего ключа нужно автоматически генерить линк на подключаемую таблицу.
Именно так все и делается .
В данном конкретном случае Вы лжете, причем проверяемо. Либо Вам придется сказать, что параметр "склад" в вашей системе не является выбираемым из справочника, либо - показать в конкретной, процитированной мной html-ке ссылку на справочник, из которого он выбирается.

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

iscrafm И здесь точно также .
Вот как? Будьте любезны: я приложу к этому письму скриншот, сделанный в IE, раз уж вы не умеете работать с FireFox, а Вы пожалуйста ткните пальцем, где в нем ссылки на описания двух справочников: складов и номенклатуры. На тот случай, если Вы скажете, что они спрятаны где-то еще, сразу приведу ответ: если так, то абсолютно точно не "так же". И должны они быть именно здесь.

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

iscrafmДумаю дальнейшее обсуждение бессмыслено.
Именно поэтому Вы не ответили, в частности, на вопрос про параметр pItemName?

1. Я не очень понимаю, чего Вы от нас хотите. Полагаете, форум "Проектирование БД" - то место, где следует искать информацию по использованию дельфового отладчика?

2. Мнение о подходе Вам уже известно.

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

4. Я понимаю, что Вам хотелось бы некоего позитива и конструктива. Но - есть такой афоризм: "Крупный ученый - тот, кто успешно решает мелкие проблемы на пути к глобальному заблуждению". Так вот, Вы просите помочь Вам стать крупным ученым в смысле этой фразы.