DRAKON.SU

Текущее время: Вторник, 04 Август, 2020 13:35

Часовой пояс: UTC + 3 часа




Начать новую тему Ответить на тему  [ Сообщений: 9 ] 
Автор Сообщение
 Заголовок сообщения: Документация
СообщениеДобавлено: Вторник, 11 Сентябрь, 2012 16:12 

Зарегистрирован: Понедельник, 09 Август, 2010 22:28
Сообщения: 128
Уважаемые коллеги.

Выкладываю документацию по проекту, которым сейчас занимаюсь. Это perl скрипт, импортирующий данные из Excel файла в БД MySQL. Данные используются в дальнейшем для SEO.

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

При документировании использован пример живых данных. Описание функций дано в отдельных HTML файлах. Пока реализовал только parse_header. При описании функции упор тоже сделан на документирование структур данных.

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

http://live-wtr.ru/1/import.html

Насколько понятна такая запись?


Вернуться к началу
 Профиль  
 
 Заголовок сообщения: Re: Документация
СообщениеДобавлено: Среда, 12 Сентябрь, 2012 06:10 

Зарегистрирован: Воскресенье, 01 Ноябрь, 2009 05:13
Сообщения: 1443
Да нормально... я пользуюсь также таблицами-описателями свойств данных (как реквизитов БД) - описание выкладывал на Драконографике. Также бывают полезны схемы ресурсов на таком языке.
Схемы связи таблиц - отдельное дело. Наверное, Вы имеете в виду не совсем то, что в IDEF1X?..


Вернуться к началу
 Профиль  
 
 Заголовок сообщения: Re: Документация
СообщениеДобавлено: Вторник, 18 Сентябрь, 2012 00:05 

Зарегистрирован: Понедельник, 09 Август, 2010 22:28
Сообщения: 128
Владислав Жаринов писал(а):
Да нормально... я пользуюсь также таблицами-описателями свойств данных (как реквизитов БД) - описание выкладывал на Драконографике. Также бывают полезны схемы ресурсов на таком языке.


Я предлагаю отказаться от специальных УГО для каждого типа данных и заменить их таблицами с поясняющими надписями, где только можно. В качестве формата использовать HTML, потому что он легко верстается и быстро грузится. А также есть возможность создания гиперссылок, позволяющих переходить в документацию на подфункции.

Владислав Жаринов писал(а):
Схемы связи таблиц - отдельное дело. Наверное, Вы имеете в виду не совсем то, что в IDEF1X?..


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

Вообще, моя идея такая: проект должен содержать метаданные, включающие в себя описание решаемой задачи и структур данных, которые будут использоваться. С последовательной декомпозицией на подзадачи. У всех проектов, с которыми я работал логика настолько проста, что там не нужен ДРАКОН. Работа кода понятна после прочтения задачи и последовательности преобразования структур данных.

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

PSV100 пошел по тому же пути, сделав документ:

download/file.php?id=3493&mode=view

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

viewtopic.php?f=27&t=2567


Вернуться к началу
 Профиль  
 
 Заголовок сообщения: Re: Документация
СообщениеДобавлено: Среда, 19 Сентябрь, 2012 10:10 

Зарегистрирован: Воскресенье, 01 Ноябрь, 2009 05:13
Сообщения: 1443
Да, я тоже думал, как всё-таки декомпозировать ИМ-схемы (стандарт IDEF1X этого не предусматривает - явно, по крайней мере). Ваше решение представляется интересным - по сути, мы берём схему ресурсов и сопоставляем каждому её процессному узлу ИМ-схему... так?..

По организации проекта - сейчас получилось изложить "литературно", что я думаю: viewtopic.php?p=74873#p74873. Понятно, что в частном случае и в графит-нотации будет как бы одна основная схема (комплект схем) - только размеченная на разных языках моделирования. Грубо говоря, переключаем язык - меняется детализация тела (схемы, скообочной структуры) да текст вершин/выносок (строк по колонкам). В общем случае и структуры моделей могут сильно разниться - но нужно сохранять соответствия в определённых направлениях. Какие есть мысли?


Вернуться к началу
 Профиль  
 
 Заголовок сообщения: Re: Документация
СообщениеДобавлено: Среда, 19 Сентябрь, 2012 17:43 

Зарегистрирован: Понедельник, 09 Август, 2010 22:28
Сообщения: 128
Владислав Жаринов писал(а):
Да, я тоже думал, как всё-таки декомпозировать ИМ-схемы (стандарт IDEF1X этого не предусматривает - явно, по крайней мере).


Что такое ИМ-схема? Пожалуйста, используйте только общепризнанные аббревиатуры.

Владислав Жаринов писал(а):
Ваше решение представляется интересным - по сути, мы берём схему ресурсов и сопоставляем каждому её процессному узлу ИМ-схему... так?..


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

Владислав Жаринов писал(а):
По организации проекта - сейчас получилось изложить "литературно", что я думаю: viewtopic.php?p=74873#p74873. Понятно, что в частном случае и в графит-нотации будет как бы одна основная схема (комплект схем) - только размеченная на разных языках моделирования. Грубо говоря, переключаем язык - меняется детализация тела (схемы, скообочной структуры) да текст вершин/выносок (строк по колонкам). В общем случае и структуры моделей могут сильно разниться - но нужно сохранять соответствия в определённых направлениях. Какие есть мысли?


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

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


Вернуться к началу
 Профиль  
 
 Заголовок сообщения: Re: Документация
СообщениеДобавлено: Пятница, 21 Сентябрь, 2012 09:48 

Зарегистрирован: Воскресенье, 01 Ноябрь, 2009 05:13
Сообщения: 1443
Вот, теперь понятно, как у Вас на верхнем уровне. Примерно так же и я вижу - общая постановка задачи, а из неё - организационно-деятельностная, как Вы говорите. Т.е. "строгая" модель, которую уже можно представить в виде "данных, операций и их связывания". Можно и данные (определения сущностей, которыми алгоритмически оперируем) ставить на "нестрогую доску" - но тут думать надо...
Да, к онтологиям формализованным тоже присматриваюсь. Для начала вижу всё просто - как "синтаксический силуэт" документа. Он тебе и словарь, и рубрикатор... :) ИМ - это официальное название вида моделирования по 1Х-стандарту - просто надоедает каждый раз регистр переключать, так что взял такое сокращение... :) Так удобно, кстати, реализовать "карту концепций", которую Мейер предлагает - просто декомпозируем не схему задачи, а документ и для его рубрик составляем частные схемы отношений...


Вернуться к началу
 Профиль  
 
 Заголовок сообщения: Re: Документация
СообщениеДобавлено: Понедельник, 22 Октябрь, 2012 18:15 

Зарегистрирован: Воскресенье, 01 Ноябрь, 2009 05:13
Сообщения: 1443
Да, вот тут ещё у Морозова кое-что можно найти в тему: viewtopic.php?p=75638#p75638. В частности, как сочетать схемы. Собственно, как я делаю, говорил выше.


Вернуться к началу
 Профиль  
 
 Заголовок сообщения: Re: Документация
СообщениеДобавлено: Пятница, 26 Октябрь, 2012 09:47 

Зарегистрирован: Понедельник, 09 Август, 2010 22:28
Сообщения: 128
Владислав Жаринов писал(а):
Да, вот тут ещё у Морозова кое-что можно найти в тему


Спасибо. Даю полную версию книги. Вы выложили извлечение.


Вложения:
Morozov_1.zip [489.82 КБ]
Скачиваний: 181
Вернуться к началу
 Профиль  
 
 Заголовок сообщения: Re: Документация
СообщениеДобавлено: Понедельник, 12 Ноябрь, 2012 11:14 

Зарегистрирован: Воскресенье, 01 Ноябрь, 2009 05:13
Сообщения: 1443
Да, как-то не задумывался о поиске полного образа, когда можно оригинал найти... ну и целиком обрабатываю только если резерв нужен... :)
    Тут, кстати, есть и ещё причина - как нетрудно догадаться, это та самая часть четвёртая... :) которую всё более ревностно пытаются соблюдать. :) И уже видится возможной ситуация, когда будут требовать буквального соблюдения соответствующих статей от любого ресурса... и как-то хочется заранее не утруждать модераторов "чисткой" хотя бы постов отдельно взятого участника оот полных образов современных изданий... :wink:
    Замечу, что и ряд вопросов на форуме не обсуждаю по аналогичным соображениям - полностью разбирать неадекватные по существу/недозволенные по форме/способам рассуждений реакции и нецелесообразно, и отъём ресурсов модераторов... :wink: А не разбирать не всегда можно - поскольку "критика - воздух науки", то необходим и противогаз... :D
В общем, вспомним известный принцип восточных единоборств: "Выигранный бой - несостоявшийся бой"... :)


Вернуться к началу
 Профиль  
 
Показать сообщения за:  Поле сортировки  
Начать новую тему Ответить на тему  [ Сообщений: 9 ] 

Часовой пояс: UTC + 3 часа


Кто сейчас на конференции

Сейчас этот форум просматривают: нет зарегистрированных пользователей и гости: 1


Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете добавлять вложения

Найти:
Вся информация, размещаемая участниками на конференции (тексты сообщений, вложения и пр.) © 2008-2020, участники конференции «DRAKON.SU», если специально не оговорено иное.
Администрация не несет ответственности за мнения, стиль и достоверность высказываний участников, равно как и за безопасность материалов, предоставляемых участниками во вложениях.
Powered by phpBB® Forum Software © phpBB Group
Русская поддержка phpBB